API Reference | BotTalk Docs

API documentation redirect

get

Redirects to the API documentation page

Responses

302

Redirect to https://bottalk.io/docs/api/

get

/api

GET /api HTTP/1.1
Host: bottalk.io
Accept: */*

302

Redirect to https://bottalk.io/docs/api/

No content

List articles

get

Returns a paginated list of articles for the authenticated project. Deleted articles are excluded.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 10 · max: 100Optional

Number of articles to return (min 10, max 100)

Default: 10

offsetintegerOptional

Number of articles to skip

Default: 0

Responses

200

List of articles

application/json

resultstringOptionalExample: ok

countintegerOptionalExample: 25

403

Authentication failed

application/json

get

/api/articles

GET /api/articles HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": "ok",
  "count": 25,
  "articles": [
    {
      "id": "a1b2c3d4",
      "external_id": "my-article-001",
      "title": "Breaking News Title",
      "text": "Full article text content...",
      "added": 1708870400,
      "updated": 1708871000,
      "status": "ready",
      "url": "https://example.com/my-article",
      "isRaw": false,
      "voice": "shimmer",
      "lang": "en-US",
      "audio": "https://audio.bottalk.io/abc123.mp3",
      "audio_duration": 42.5,
      "audio_preview": "https://audio.bottalk.io/preview_abc123.mp3",
      "audio_preview_duration": 15
    }
  ]
}

Create article

post

Creates a new article and queues it for audio generation. Requires a full API token (not readonly). If externalId is provided it must be unique across all articles.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

titlestringRequired

Article title

Example: Breaking News Title

textstringRequired

Article body text (HTML allowed if parse=true)

Example: Full article text or HTML content...

urlstringOptional

Original article URL

Example: https://example.com/my-article

externalIdstringOptional

Unique ID for external control. If an article with this ID already exists, a 400 error is returned.

Example: my-article-001

voicestringOptional

TTS voice name. Must be used together with lang. Available voices: echo, fable, alloy, onyx, nova, shimmer (support de-DE, en-US), de-DE-ConradNeural, de-DE-KatjaNeural (support de-DE)

Example: shimmer

langstringOptional

Voice language/locale. Must be used together with voice. Examples: de-DE, en-US

Example: en-US

parsebooleanOptional

If true, HTML is stripped and text is cleaned before processing

Default: false

isRawbooleanOptional

If true, text is treated as raw (no additional processing)

Default: false

promptstringOptional

Individual prompt for audio generation (valid for Gemini Vertex model)

labelsstring[]Optional

List of labels to attach to this article

Example: ["sports","breaking"]

Responses

200

Article created successfully

application/json

resultstringOptionalExample: ok

idstringOptional

Slug of the newly created article

Example: a1b2c3d4

400

Validation error or duplicate externalId

application/json

403

Authentication failed

application/json

post

/api/articles

POST /api/articles HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "title": "My Article",
  "text": "Article body text goes here."
}

{
  "result": "ok",
  "id": "a1b2c3d4"
}

Get article by ID

get

Returns full article details by its internal slug ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

articleIdstringRequired

Article slug (internal ID returned on create)

Example: a1b2c3d4

Responses

200

Article found

application/json

resultstringOptionalExample: ok

403

Authentication failed

application/json

200 (not found)

Article not found (returns 200 with error result)

application/json

get

/api/articles/{articleId}

GET /api/articles/{articleId} HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": "ok",
  "article": {
    "id": "a1b2c3d4",
    "externalId": "my-article-001",
    "title": "Breaking News Title",
    "text": "Full article text content...",
    "prompt": "text",
    "added": 1708870400,
    "updated": 1708871000,
    "status": "ready",
    "url": "https://example.com/my-article",
    "isRaw": false,
    "voice": "shimmer",
    "lang": "en-US",
    "type": [
      {
        "Name": "TYPE_NACHRICHT",
        "Score": 0.203
      },
      {
        "Name": "TYPE_KOMMENTAR",
        "Score": 0.148
      }
    ],
    "audio": "https://audio.bottalk.io/abc123.mp3",
    "audio_duration": 42.5,
    "audio_preview": "https://audio.bottalk.io/preview_abc123.mp3",
    "audio_preview_duration": 15,
    "error": "text",
    "errors": [
      {
        "error": "text",
        "date": "2024-02-25 12:00:00"
      }
    ]
  }
}

Update article by ID

put

Updates article content and triggers audio re-generation. Requires a full API token (not readonly). Labels are fully replaced — any existing labels not present in the request will be removed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

articleIdstringRequired

Article slug (internal ID)

Example: a1b2c3d4

Body

titlestringRequiredExample: Updated Article Title

textstringRequiredExample: Updated article body text...

urlstringOptionalExample: https://example.com/my-article

externalIdstringOptional

Update the external ID (must be unique)

Example: my-article-001

voicestringOptionalExample: shimmer

langstringOptionalExample: en-US

parsebooleanOptionalDefault: false

isRawbooleanOptional

promptstring · nullableOptional

Individual prompt for audio generation (valid for Gemini Vertex model). Set to null to remove.

labelsstring[]Optional

Full replacement of labels (existing labels not in list will be removed)

Example: ["sports"]

Responses

200

Article updated successfully

application/json

resultstringOptionalExample: ok

idstringOptionalExample: a1b2c3d4

400

Validation error or duplicate externalId

application/json

401

Article belongs to a different project

application/json

403

Authentication failed

application/json

put

/api/articles/{articleId}

PUT /api/articles/{articleId} HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "title": "Updated Article Title",
  "text": "Updated article body text...",
  "url": "https://example.com/my-article",
  "externalId": "my-article-001",
  "voice": "shimmer",
  "lang": "en-US",
  "parse": false,
  "isRaw": true,
  "prompt": "text",
  "labels": [
    "sports"
  ]
}

{
  "result": "ok",
  "id": "a1b2c3d4"
}

Delete article

delete

Marks the article as deleted. Deleted articles are excluded from list responses. Requires a full API token (not readonly).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

articleIdstringRequired

Article slug (internal ID)

Example: a1b2c3d4

Responses

200

Article deleted

application/json

resultstring · enumOptionalExample: okPossible values:

403

Authentication failed

application/json

404

Article not found or already deleted

application/json

delete

/api/articles/{articleId}

DELETE /api/articles/{articleId} HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": "ok"
}

Get article by external ID

get

Returns full article details by the external ID you provided on creation.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

externalIdstringRequired

Your external article identifier

Example: my-article-001

Responses

200

Article found

application/json

resultstringOptionalExample: ok

403

Authentication failed

application/json

200 (not found)

Article not found (returns 200 with error result)

application/json

get

/api/articles_external_id/{externalId}

GET /api/articles_external_id/{externalId} HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": "ok",
  "article": {
    "id": "a1b2c3d4",
    "externalId": "my-article-001",
    "title": "Breaking News Title",
    "text": "Full article text content...",
    "prompt": "text",
    "added": 1708870400,
    "updated": 1708871000,
    "status": "ready",
    "url": "https://example.com/my-article",
    "isRaw": false,
    "voice": "shimmer",
    "lang": "en-US",
    "type": [
      {
        "Name": "TYPE_NACHRICHT",
        "Score": 0.203
      },
      {
        "Name": "TYPE_KOMMENTAR",
        "Score": 0.148
      }
    ],
    "audio": "https://audio.bottalk.io/abc123.mp3",
    "audio_duration": 42.5,
    "audio_preview": "https://audio.bottalk.io/preview_abc123.mp3",
    "audio_preview_duration": 15,
    "error": "text",
    "errors": [
      {
        "error": "text",
        "date": "2024-02-25 12:00:00"
      }
    ]
  }
}

Update article by external ID

put

Updates article by external ID and triggers audio re-generation. Requires a full API token (not readonly).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

externalIdstringRequired

Your external article identifier

Example: my-article-001

Body

titlestringRequiredExample: Updated Article Title

textstringRequiredExample: Updated article body text...

urlstringOptionalExample: https://example.com/my-article

externalIdstringOptional

Update the external ID (must be unique)

Example: my-article-001

voicestringOptionalExample: shimmer

langstringOptionalExample: en-US

parsebooleanOptionalDefault: false

isRawbooleanOptional

promptstring · nullableOptional

Individual prompt for audio generation (valid for Gemini Vertex model). Set to null to remove.

labelsstring[]Optional

Full replacement of labels (existing labels not in list will be removed)

Example: ["sports"]

Responses

200

Article updated successfully

application/json

resultstringOptionalExample: ok

idstringOptionalExample: a1b2c3d4

400

Validation error or duplicate externalId

application/json

403

Authentication failed

application/json

404

Article not found by externalId

application/json

put

/api/articles_external_id/{externalId}

PUT /api/articles_external_id/{externalId} HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "title": "Updated Article Title",
  "text": "Updated article body text...",
  "url": "https://example.com/my-article",
  "externalId": "my-article-001",
  "voice": "shimmer",
  "lang": "en-US",
  "parse": false,
  "isRaw": true,
  "prompt": "text",
  "labels": [
    "sports"
  ]
}

{
  "result": "ok",
  "id": "a1b2c3d4"
}

Get article by URL

get

Returns full article details by the original article URL.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

externalUrlstringRequired

Original article URL (URL-encoded)

Example: https%3A%2F%2Fexample.com%2Fmy-article

Responses

200

Article found

application/json

resultstringOptionalExample: ok

403

Authentication failed

application/json

200 (not found)

Article not found (returns 200 with error result)

application/json

get

/api/articles_external_url/{externalUrl}

GET /api/articles_external_url/{externalUrl} HTTP/1.1
Host: bottalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": "ok",
  "article": {
    "id": "a1b2c3d4",
    "externalId": "my-article-001",
    "title": "Breaking News Title",
    "text": "Full article text content...",
    "prompt": "text",
    "added": 1708870400,
    "updated": 1708871000,
    "status": "ready",
    "url": "https://example.com/my-article",
    "isRaw": false,
    "voice": "shimmer",
    "lang": "en-US",
    "type": [
      {
        "Name": "TYPE_NACHRICHT",
        "Score": 0.203
      },
      {
        "Name": "TYPE_KOMMENTAR",
        "Score": 0.148
      }
    ],
    "audio": "https://audio.bottalk.io/abc123.mp3",
    "audio_duration": 42.5,
    "audio_preview": "https://audio.bottalk.io/preview_abc123.mp3",
    "audio_preview_duration": 15,
    "error": "text",
    "errors": [
      {
        "error": "text",
        "date": "2024-02-25 12:00:00"
      }
    ]
  }
}

hashtagAPI documentation redirect

hashtagList articles

hashtagCreate article

hashtagGet article by ID

hashtagUpdate article by ID

hashtagDelete article

hashtagGet article by external ID

hashtagUpdate article by external ID

hashtagGet article by URL

API documentation redirect

List articles

Create article

Get article by ID

Update article by ID

Delete article

Get article by external ID

Update article by external ID

Get article by URL