> 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/grow/directory/free-recommendations.md).

# Free Recommendations

## Free Recommendations

The free-recommendations directory: the Partner Network catalog of newsletters this publication can recommend for free, plus the two actions taken from it — **recommend** one, or **request a partnership** (ask them to recommend you back).

### Browse the directory

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

Paginated. Returns active newsletters opted into the directory, excluding this publication and any it has archived.

**Path Parameters**

| Name                                                | Type   | Description                                              |
| --------------------------------------------------- | ------ | -------------------------------------------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication a recommendation would be attributed to. |

**Query Parameters**

| Name       | Type   | Description                                                  |
| ---------- | ------ | ------------------------------------------------------------ |
| q          | String | Free-text search.                                            |
| categories | String | Comma-separated category names (matched case-insensitively). |
| language   | String | Filter by language.                                          |

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

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

{% endtab %}
{% endtabs %}

### Get a directory entry

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

On a single entry the object also carries the per-caller `already_recommended` and `partnership_request_pending` flags.

**Path Parameters**

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

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Add a free recommendation

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/grow/directory/free_recommendations/:free_recommendation_uuid/recommend`

Starts recommending the target publication for free. Returns the created **Recommendation**.

**Path Parameters**

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

{% tabs %}
{% tab title="201: Created" %}

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

{% endtab %}
{% endtabs %}

### Request a partnership

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/grow/directory/free_recommendations/:free_recommendation_uuid/partnership_request`

Asks the target publication to recommend this one back.

**Path Parameters**

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

{% tabs %}
{% tab title="201: Created" %}

```json
{
  "partnership_request": <Partnership Request Object>
}
```

{% endtab %}
{% endtabs %}