# Articles

## Creating a new article

## Create article.

<mark style="color:green;">`POST`</mark> `https://bottalk.io/api/articles`

Creates a new audio article inside of a project.

#### Request Body

| Name                                    | Type         | Description                                                                                                     |
| --------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
| title<mark style="color:red;">\*</mark> | string       | The title of the article                                                                                        |
| text<mark style="color:red;">\*</mark>  | string       | The main content of the article.                                                                                |
| url<mark style="color:red;">\*</mark>   | string       | The page url of the original article                                                                            |
| parse                                   | boolean      | Should BotTalk parse HTML inside of the article?                                                                |
| labels                                  | array        | Labels to assign to the article inside BotTalk.                                                                 |
| externalId                              | string\|null | uniq id for external control, this field in uniq, and if already exists we will answer by 400 http status code. |
| voice                                   | String       | The voice from list for audify article                                                                          |
| lang                                    | String       | The language from list for audify article                                                                       |
| prompt                                  | String       | Individual prompt for an article creation (Valid for Gemini Vertex Model)                                       |

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

```javascript
{
  "result": "ok",
  "id": "b49f2511d9033f313b8c0d361687cd5f"
}
```

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}

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

```json
{
  "result": "error",
  "message": "article with externalId='123456789' already exists"
}
```

{% endtab %}
{% endtabs %}

## Retrieving an aritcle

## Fetch article.

<mark style="color:blue;">`GET`</mark> `https://bottalk.io/api/articles/{id}`

Fetches an article by `id`

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

```javascript
{
  "result": "ok",
  "article": {
    "id": "90ae27149dba7f5fbf4269b9318ba9cb",
    "externalId": "321654",
    "title": "Test title 5",
    "text": "Test text 09",
    "added": 1573133305,
    "status": "ready",
    "voice": "de-DE-ConradNeural",
    "lang": "de-DE",
    "prompt": null,
    "url": "https://test.de/article.html",     
    "type": [
                 {
                   "Name": "TYPE_NACHRICHT",
                   "Score": 0.20319999754428864
                 },
                 {
                   "Name": "TYPE_KOMMENTAR",
                   "Score": 0.14839999377727509
                 },
                 {
                   "Name": "TYPE_LIVE_TICKER",
                   "Score": 0.12219999730587006
                 }
           ],
    "audio": "https:\/\/bottalk.io\/audio\/d67e6dd172ab320880a158fd17fcf4f4.mp3"
  }
}
```

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

## Retrieving an article by external\_id

<mark style="color:blue;">`GET`</mark> `https://bottalk.io/api/articles_external_id/{external_id}`

response same as for retrieve an article method

## Retrieving an article by URL

In some cases - for instance - to integrate into your custom mobile app - you need to fetch an article by the external URL.

<mark style="color:blue;">`GET`</mark> `https://bottalk.io/api/articles_external_url/{external_url}`

Please note that the `external_url` parameter should be URL encoded.

## Retrieving multiple articles

## Fetch multiple articles.

<mark style="color:blue;">`GET`</mark> `https://bottalk.io/api/articles?limit={n}&offset={m}`

Fetches articles from the project.

#### Query Parameters

| Name   | Type    | Description                               |
| ------ | ------- | ----------------------------------------- |
| limit  | integer | Number of articles to retrieve            |
| offset | integer | Offset of the results if they are limited |

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

```javascript
{
  "result": "ok",
  "article": {
    "id": "90ae27149dba7f5fbf4269b9318ba9cb",
    "title": "Test title 5",
    "text": "Test text 09",
    "added": 1573133305,
    "status": "ready",
    "url": "https://test.de/article.html",     
    "type": [
                 {
                   "Name": "TYPE_NACHRICHT",
                   "Score": 0.20319999754428864
                 },
                 {
                   "Name": "TYPE_KOMMENTAR",
                   "Score": 0.14839999377727509
                 },
                 {
                   "Name": "TYPE_LIVE_TICKER",
                   "Score": 0.12219999730587006
                 }
           ],
    "audio": "https:\/\/bottalk.io\/audio\/d67e6dd172ab320880a158fd17fcf4f4.mp3"
  }
}
```

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

## Updating an article

## Update article.

<mark style="color:orange;">`PUT`</mark> `https://bottalk.io/api/articles/{id}`

Updates a audio article.

#### Request Body

| Name                                    | Type    | Description                                      |
| --------------------------------------- | ------- | ------------------------------------------------ |
| title<mark style="color:red;">\*</mark> | string  | The title of the article                         |
| text<mark style="color:red;">\*</mark>  | string  | The main content of the article.                 |
| url<mark style="color:red;">\*</mark>   | string  | The page url of the original article             |
| labels                                  | array   | Labels to assign to the article inside BotTalk.  |
| parse                                   | boolean | Should BotTalk parse HTML inside of the article? |
| voice                                   | String  | Voice "de-DE-ConradNeural"                       |
| lang                                    | String  | de-DE,en-US, language                            |

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

```javascript
{
  "result": "ok",
  "id": "b49f2511d9033f313b8c0d361687cd5f"
}
```

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

## Updating an article by external id

## Update article by external\_id

<mark style="color:orange;">`PUT`</mark> `https://bottalk.io/api/articles_external_id/{external_id}`

Updates an audio article.

All params and responses same as for Update Article ***/api/articles/{id}***

## Deleting an article

## Delete an article.

<mark style="color:red;">`DELETE`</mark> `https://bottalk.io/api/articles/{id}`

Deletes an article from the project.

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

```javascript
{
  "result": "ok"
}
```

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

### Article Status

| status                                      | description                                                                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:green;">ready</mark>     | the article is ready and audiofile exists                                                                                                         |
| <mark style="color:blue;">processing</mark> | the audification is in progress                                                                                                                   |
| <mark style="color:purple;">retry</mark>    | tts provider or normalizer has returned an error, bottalk will try the audification again in the near future (article has been sent to the queue) |
| <mark style="color:yellow;">waiting</mark>  | the article is waiting to be audified                                                                                                             |
| rejected                                    | the article is rejected by audio automation rules                                                                                                 |
| <mark style="color:red;">errored</mark>     | the article contains an error which prevented audification                                                                                        |

## Voice and Language fields

example: {"voice":"de-DE-ConradNeural", "lang":"de-DE"}

| Voice              | Lang (list separated by comma, you can choose one of them) |
| ------------------ | ---------------------------------------------------------- |
| echo               | de-DE,en-US                                                |
| fable              | de-DE,en-US                                                |
| alloy              | de-DE,en-US                                                |
| onyx               | de-DE,en-US                                                |
| nova               | de-DE,en-US                                                |
| shimmer            | de-DE,en-US                                                |
| de-DE-ConradNeural | de-DE                                                      |
| de-DE-KatjaNeural  | de-DE                                                      |
|                    |                                                            |