Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

BotTalk Publishers API

API documentation redirect

get

Redirects to the API documentation page

Responses
302

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

No content
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
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
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
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
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:
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
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
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
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"
      }
    ]
  }
}
PreviousAPI
NextModels

Last updated