# 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 %}