> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/endpoints/publications/earn/recommendations.md).

# Recommendations

## Recommendations

A **paid recommendation** is a partner-program-backed recommendation this publication earns a commission from (the Earn side). Use this resource to list the paid recommendations the publication is currently making, fetch a single one by UUID, archive, or re-activate. Browse and recommend new programs from the **Directory** sub-resource; free recommendations live under **Grow**.

### List recommendations

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/earn/recommendations`

Paginated. Omit `status` to list non-archived rows (`active` + `awaiting_approval`).

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

**Query Parameters**

| Name   | Type   | Description                                                                                                                                                        |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| status | String | Optional filter: `active` (recommendable with budget), `budget_used_up`, `paused`, `awaiting_approval`, or `archived`. Omit for all non-archived. Invalid → `400`. |
| expand | String | `recommended_publication`, `stats`.                                                                                                                                |
| from   | String | Start date (`YYYY-MM-DD`) for `stats`.                                                                                                                             |
| to     | String | End date (`YYYY-MM-DD`) for `stats`.                                                                                                                               |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "recommendations": [
    <Recommendation Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_recommendations": 8
  }
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  "error": "Unsupported `status`. Valid values: active, budget_used_up, paused, awaiting_approval, archived."
}
```

{% endtab %}
{% endtabs %}

### Get recommendation

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/earn/recommendations/:uuid`

**Path Parameters**

| Name                                                | Type   | Description                |
| --------------------------------------------------- | ------ | -------------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID.    |
| uuid<mark style="color:red;">\*</mark>              | String | The recommendation's UUID. |

**Query Parameters**

| Name   | Type   | Description                         |
| ------ | ------ | ----------------------------------- |
| expand | String | `recommended_publication`, `stats`. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "recommendation": <Recommendation Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### Archive a recommendation

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/earn/recommendations/:recommendation_uuid/archive`

Soft-archives the paid recommendation so it stops appearing in active lists. Reversible with **re-activate** when this publication (the partner) archived it.

**Path Parameters**

| Name                                                   | Type   | Description                |
| ------------------------------------------------------ | ------ | -------------------------- |
| publication\_uuid<mark style="color:red;">\*</mark>    | String | The publication's UUID.    |
| recommendation\_uuid<mark style="color:red;">\*</mark> | String | The recommendation's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "recommendation": <Recommendation Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}
{% endtabs %}

### Re-activate a recommendation

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/earn/recommendations/:recommendation_uuid/reactivation`

Restores a soft-archived paid recommendation. Only works when **this publication** (the partner) archived it.

**Path Parameters**

| Name                                                   | Type   | Description                |
| ------------------------------------------------------ | ------ | -------------------------- |
| publication\_uuid<mark style="color:red;">\*</mark>    | String | The publication's UUID.    |
| recommendation\_uuid<mark style="color:red;">\*</mark> | String | The recommendation's UUID. |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "recommendation": <Recommendation Object>
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
  "error": "Resource not found."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "error": "This recommendation was archived by the sponsor and can't be re-activated."
}
```

{% endtab %}
{% endtabs %}