# Models

## The Article object

```json
{"openapi":"3.0.3","info":{"title":"BotTalk Publishers API","version":"1.0.0"},"components":{"schemas":{"Article":{"type":"object","properties":{"id":{"type":"string","description":"Article slug (internal ID)"},"externalId":{"type":"string","nullable":true,"description":"Unique ID for external control. If an article with this ID already exists, a 400 error is returned."},"title":{"type":"string"},"text":{"type":"string"},"prompt":{"type":"string","nullable":true,"description":"Individual prompt for audio generation (valid for Gemini Vertex model)"},"added":{"type":"integer","description":"Unix timestamp when article was created"},"updated":{"type":"integer","nullable":true,"description":"Unix timestamp of last processing"},"status":{"type":"string","enum":["waiting","processing","ready","errored","deleted","retry","fallback","no_money","limit_reached","rejected","parsed","recrawling"],"description":"Article processing status:\n- `ready` — article is ready and audio file exists\n- `processing` — audification is in progress\n- `waiting` — article is waiting to be audified\n- `retry` — TTS provider returned an error, will retry automatically\n- `rejected` — article rejected by audio automation rules\n- `errored` — error which prevented audification\n- `deleted` — article has been deleted\n- `fallback` — using fallback TTS provider\n- `no_money` — insufficient balance\n- `limit_reached` — daily article limit reached\n- `parsed` — article parsed, awaiting audification\n- `recrawling` — article content is being re-fetched\n"},"url":{"type":"string","nullable":true,"description":"Original article URL"},"isRaw":{"type":"boolean","description":"Whether article text is raw (no HTML stripping)"},"voice":{"type":"string","description":"TTS voice name. Available voices:\n`echo`, `fable`, `alloy`, `onyx`, `nova`, `shimmer` (support `de-DE`, `en-US`),\n`de-DE-ConradNeural`, `de-DE-KatjaNeural` (support `de-DE`)\n"},"lang":{"type":"string","description":"Voice language/locale. Must match the selected voice.\nExamples: `de-DE`, `en-US`\n"},"type":{"type":"array","nullable":true,"description":"Content type scores from comprehend analysis (only if detected)","items":{"type":"object","properties":{"Name":{"type":"string"},"Score":{"type":"number","format":"float"}}}},"audio":{"type":"string","nullable":true,"description":"Full audio MP3 URL (only when ready)"},"audio_duration":{"type":"number","nullable":true,"description":"Full audio duration in seconds"},"audio_preview":{"type":"string","nullable":true,"description":"Preview audio MP3 URL (only when ready)"},"audio_preview_duration":{"type":"number","nullable":true,"description":"Preview audio duration in seconds"},"error":{"type":"string","nullable":true,"description":"Last error message (only when status=errored)"},"errors":{"type":"array","nullable":true,"description":"Error history (only when status=errored)","items":{"type":"object","properties":{"error":{"type":"string"},"date":{"type":"string","format":"date-time"}}}}}}}}}
```

## The ArticleListItem object

```json
{"openapi":"3.0.3","info":{"title":"BotTalk Publishers API","version":"1.0.0"},"components":{"schemas":{"ArticleListItem":{"type":"object","description":"Abbreviated article object returned in list responses","properties":{"id":{"type":"string"},"external_id":{"type":"string","nullable":true},"title":{"type":"string"},"text":{"type":"string"},"added":{"type":"integer"},"updated":{"type":"integer","nullable":true},"status":{"type":"string"},"url":{"type":"string","nullable":true},"isRaw":{"type":"boolean"},"voice":{"type":"string"},"lang":{"type":"string"},"audio":{"type":"string","nullable":true},"audio_duration":{"type":"number","nullable":true},"audio_preview":{"type":"string","nullable":true},"audio_preview_duration":{"type":"number","nullable":true}}}}}}
```

## The ArticleCreateRequest object

```json
{"openapi":"3.0.3","info":{"title":"BotTalk Publishers API","version":"1.0.0"},"components":{"schemas":{"ArticleCreateRequest":{"type":"object","required":["title","text"],"properties":{"title":{"type":"string","description":"Article title"},"text":{"type":"string","description":"Article body text (HTML allowed if parse=true)"},"url":{"type":"string","description":"Original article URL"},"externalId":{"type":"string","description":"Unique ID for external control. If an article with this ID already exists, a 400 error is returned."},"voice":{"type":"string","description":"TTS voice name. Must be used together with `lang`.\nAvailable voices: `echo`, `fable`, `alloy`, `onyx`, `nova`, `shimmer` (support `de-DE`, `en-US`),\n`de-DE-ConradNeural`, `de-DE-KatjaNeural` (support `de-DE`)\n"},"lang":{"type":"string","description":"Voice language/locale. Must be used together with `voice`.\nExamples: `de-DE`, `en-US`\n"},"parse":{"type":"boolean","description":"If true, HTML is stripped and text is cleaned before processing","default":false},"isRaw":{"type":"boolean","description":"If true, text is treated as raw (no additional processing)","default":false},"prompt":{"type":"string","description":"Individual prompt for audio generation (valid for Gemini Vertex model)"},"labels":{"type":"array","description":"List of labels to attach to this article","items":{"type":"string"}}}}}}}
```

## The ArticleUpdateRequest object

```json
{"openapi":"3.0.3","info":{"title":"BotTalk Publishers API","version":"1.0.0"},"components":{"schemas":{"ArticleUpdateRequest":{"type":"object","required":["title","text"],"properties":{"title":{"type":"string"},"text":{"type":"string"},"url":{"type":"string"},"externalId":{"type":"string","description":"Update the external ID (must be unique)"},"voice":{"type":"string"},"lang":{"type":"string"},"parse":{"type":"boolean","default":false},"isRaw":{"type":"boolean"},"prompt":{"type":"string","nullable":true,"description":"Individual prompt for audio generation (valid for Gemini Vertex model). Set to null to remove."},"labels":{"type":"array","description":"Full replacement of labels (existing labels not in list will be removed)","items":{"type":"string"}}}}}}}
```

## The SuccessResult object

```json
{"openapi":"3.0.3","info":{"title":"BotTalk Publishers API","version":"1.0.0"},"components":{"schemas":{"SuccessResult":{"type":"object","properties":{"result":{"type":"string","enum":["ok"]}}}}}}
```

## The ErrorResult object

```json
{"openapi":"3.0.3","info":{"title":"BotTalk Publishers API","version":"1.0.0"},"components":{"schemas":{"ErrorResult":{"type":"object","properties":{"result":{"type":"string","enum":["error","fail"]},"message":{"type":"string"}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.bottalk.io/docs/api/models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.