> For the complete documentation index, see [llms.txt](https://docs.bottalk.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bottalk.io/docs/help/endpoints/articles.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.bottalk.io/docs/help/endpoints/articles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.