# Publications

## Create a publication

<mark style="color:green;">`POST`</mark> `https://api.sparkloop.app/v2/publications`

#### Request Body

| Name                                               | Type   | Description                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>             | string | Name                                                                                                                                                                                                                                                                                                                                                            |
| description                                        | string | Description                                                                                                                                                                                                                                                                                                                                                     |
| categories<mark style="color:red;">\*</mark>       | array  | <p>Categories to which this publication belongs, at least one and at most three categories are allowed.<br><br>e.g. \[marketing, tech]<br><br>List of all available categories: marketing, tech, food & drink, sports, health & fitness, news, finance, web3.0, TV & movie, literature, science, politics, lifestyle, business, art & design, travel, media</p> |
| list\_id                                           | string | The ID of the ESP list you want to use for this publication. Some ESPs like ConvertKit don't use lists so you can leave the `list_id` empty in that case.                                                                                                                                                                                                       |
| status                                             | string | <p>Status of the publication.<br><br><code>active</code> or <code>archived</code></p>                                                                                                                                                                                                                                                                           |
| logo<mark style="color:red;">\*</mark>             | image  | Logo of the publication. Must be png, jpeg, or jpg, and smaller than 1MB in size.                                                                                                                                                                                                                                                                               |
| audience\_gender<mark style="color:red;">\*</mark> | string | <p>Gender composition of the publication audience.<br></p><p>It can be <code>almost\_all\_male</code>, <code>mainly\_male</code>, <code>mixed</code>, <code>mainly\_female</code> or <code>almost\_all\_female</code></p>                                                                                                                                       |
| income\_levels<mark style="color:red;">\*</mark>   | array  | <p>Income levels of the publication audience. At least one is required.<br><br>e.g. \[$150k+]<br><br>List of all available income levels:</p><p><code>less than $20k</code>, <code>$20k - $50k</code>, <code>$50k - $75k</code>, <code>$75k - $100k</code>, <code>$100k - $150k</code>, <code>$150k+</code></p>                                                 |
| age\_ranges<mark style="color:red;">\*</mark>      | array  | <p>Age ranges the publication audience belongs to. At least one is required.<br><br>e.g. \[under 18]<br><br>List of all available age ranges:</p><p><code>under 18</code>, <code>18 - 24</code>, <code>25 - 39</code>, <code>40 - 59</code>, <code>60+</code></p>                                                                                               |

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

```json
{
  "publication": <Publication Object>
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="undefined" %}

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Get publications

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v2/publications`

Publications are ordered descendingly by *created\_at*, meaning the first page shows the latest publications.

{% tabs %}
{% tab title="200 Used query params ?page=1\&per\_page=2" %}

```json
{
  "publications": [
    <Publication Object>,
    <Publication Object>
  ],
  "meta": {
    "per_page": 2,
    "page": 1,
    "total_pages": 2,
    "total_publications": 4
  }
}
```

{% endtab %}
{% endtabs %}

## Get a publication

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v2/publications/:identifier`

Returns a single publication by UUID

#### Path Parameters

| Name                                         | Type   | Description        |
| -------------------------------------------- | ------ | ------------------ |
| identifier<mark style="color:red;">\*</mark> | string | Publication's UUID |

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

```json
{
  "publication": <Publication Object>
}
```

{% endtab %}

{% tab title="404 " %}
{% tabs %}
{% tab title="Publication not found" %}

```
{
    "error": "Publication pub_4bc10562d97 not found!"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Update publication

<mark style="color:orange;">`PUT`</mark> `https://api.sparkloop.app/v2/publications/:identifier`

#### Path Parameters

| Name                                         | Type   | Description        |
| -------------------------------------------- | ------ | ------------------ |
| identifier<mark style="color:red;">\*</mark> | string | Publication's UUID |

#### Request Body

| Name             | Type    | Description                                                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name             | string  | Name                                                                                                                                                                                                                                                                                                                                                            |
| description      | string  | Description                                                                                                                                                                                                                                                                                                                                                     |
| categories       | array   | <p>Categories to which this publication belongs, at least one and at most three categories are allowed.<br><br>e.g. \[marketing, tech]<br><br>List of all available categories: marketing, tech, food & drink, sports, health & fitness, news, finance, web3.0, TV & movie, literature, science, politics, lifestyle, business, art & design, travel, media</p> |
| logo             | String  | Logo of the publication. Must be png, jpeg, or jpg, and smaller than 1MB in size.                                                                                                                                                                                                                                                                               |
| status           | String  | <p>Status of the publication.<br><br><code>active</code> or <code>archived</code></p>                                                                                                                                                                                                                                                                           |
| auto\_pilot      | boolean | Set to `true` to enable auto-pilot. Set to `false` to disable it.                                                                                                                                                                                                                                                                                               |
| audience\_gender | string  | <p>Gender composition of the publication audience.<br></p><p>It can be <code>almost\_all\_male</code>, <code>mainly\_male</code>, <code>mixed</code>, <code>mainly\_female</code> or <code>almost\_all\_female</code></p>                                                                                                                                       |
| income\_levels   | array   | <p>Income levels of the publication audience. At least one is required.</p><p></p><p>e.g. \[$150k+]</p><p></p><p>List of all available income levels:</p><p><code>less than $20k</code>, <code>$20k - $50k</code>, <code>$50k - $75k</code>, <code>$75k - $100k</code>, <code>$100k - $150k</code>, <code>$150k+</code><br></p>                                 |
| age\_ranges      | array   | <p>Age ranges the publication audience belongs to. At least one is required.<br><br>e.g. \[under 18]<br><br>List of all available age ranges:</p><p><code>under 18</code>, <code>18 - 24</code>, <code>25 - 39</code>, <code>40 - 59</code>, <code>60+</code></p>                                                                                               |

{% tabs %}
{% tab title="200 Returns the subscriber." %}

```json
{
  "publication": <Publication Object>
}
```

{% endtab %}

{% tab title="400 When you try setting status to something other than unsubscribed or confirmed." %}

{% endtab %}

{% tab title="404 " %}
{% tabs %}
{% tab title="Publication not found" %}

```json
{
    "error": "Publication pub_34c8e39ca4 not found!"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Delete publication

<mark style="color:red;">`DELETE`</mark> `https://api.sparkloop.app/v2/publications/:identifier`

#### Path Parameters

| Name                                         | Type   | Description        |
| -------------------------------------------- | ------ | ------------------ |
| identifier<mark style="color:red;">\*</mark> | string | Publication's UUID |

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

```
{
    "message": "Successfully deleted publication pub_34c8e39cf4"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "error": "Failed to delete publication pub_34c8e39ca4"
}
```

{% endtab %}

{% tab title="404 " %}
{% tabs %}
{% tab title="Publication not found" %}

```
{
    "error": "Publication pub_34c8e39ca4 not found!"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sparkloop.app/api-v2/endpoints/subscribers-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.