News

/api/v1/news creates the same private dated episode as the Mini App: it appears in the owner’s News archive, follows the owner’s ready-notification preferences and never enters the Podcast feed.

Materials and narration

Search respects the period captured in the order. Complete extracted originals retain their identities and provenance; models read their pages without another paid extraction. A known URL refusal during agent reading is returned for that address; admissible pages in the batch can still be read. A forbidden address is neither dispatched nor given a paid read. Retained originals are reused before fresh DNS admission, while each new request and redirect retains network safety checks. This outcome does not prove the remaining material is complete or authorize repeating an unknown external effect. A retained error from an individual search or extraction is returned to the author as data. The author can continue from other genuine originals or make a different permitted request. The original uncertain request is not dispatched again, including in another read batch containing the same URLs. An error does not replace a read source. An episode may be ready to play while the earlier request’s expense remains in reconciliation with its hold retained. Search snippets and notifications help discover links. The research agent assesses the originals’ relevance and content against the captured UTC observation time asOf. Publication, event and discovery dates have different meanings. An unknown publication date stays unknown; the requested period does not establish a missing date. An earlier preview does not prove that an event occurred.

After research, the author prepares one complete narration in the selected language. Separate paid writers and auditors for each source or block are not required. The author owns coherence, explanations and source support; code checks response structure and authority over retained materials. A glossary, when supplied by the author, is delivered separately from narration. The common research instruction asks the author to preserve what each number counts, its unit and period, distinguishing plans or capacity from results and intentions from completed actions in the memo, headline and summary. The author checks final wording against originals and corrects language in the same call; no separate paid review is added. Completed text is retained for continuation. If a known response is cut off by the model’s output limit, its saved prefix is continued without repurchasing the beginning.

Duration is a guide. A shorter substantive episode is valid; estimated words, characters, minutes and source counts do not by themselves cause refusal or paid rewriting. Models can make mistakes, so their decisions do not guarantee quality. No events, no confirmation, interrupted discovery and processing failure remain distinct; confirmed costs stay on the receipt. An unknown external outcome is not declared successful. task.errorCode retains NEWS_RESEARCH_UNCONFIRMED when discovered material could not be confirmed for the selected topic and period, and NEWS_RESEARCH_INCOMPLETE when research did not finish. The Telegram notification explains the same reason in Russian or English without provider error text. A completed search without relevant events cancels the edition without inventing audio.

Endpoints

Method and path	Scope	Result
GET /api/v1/news/voices	news:quote	available voices
POST /api/v1/news/quotes	news:quote	201 {quote} with quoteId, credits, maximumCredits, expectedCredits, forecast, expiresAt
POST /api/v1/news	news:create	202 {operation: {taskId, status: "started"}}
GET /api/v1/news/:taskId	news:read	{task: {taskId, status, stageCode, progressPercent, balancePause?, recovery?, accounting?, errorCode?}}
GET /api/v1/news/:taskId/result	news:read	text, topic, period, voice, duration, sources and glossary
GET /api/v1/news/:taskId/receipt	news:read	{receipt}
POST /api/v1/news/:taskId/cancel	news:create	{success: true}
GET /api/v1/news/:taskId/audio	news:read	audio, supports Range

stageCode is queued, researching, drafting, synthesizing, paused_insufficient_credits, ready, failed or cancelled. Until the episode is ready, result and audio answer 409 NEWS_NOT_READY; a finished episode cannot be cancelled (409 NEWS_NOT_CANCELLABLE).

expectedCredits is an approximate cost; forecast shows supported estimate bounds and confidence. Unavailable bounds remain null instead of a fabricated range. The response’s maximumCredits: null means balance-funded work without an episode cap. Developer News does not accept this request field; use the creating key’s separate quota to limit key spending. Create does not hold the full limit: completed paid actions are charged as they run. If the balance cannot fund the next action, the task enters paused_insufficient_credits and resumes with the same taskId after a top-up. The receipt shows credits already charged; they remain charged after cancellation or failure. An explicit numeric limit and key quota intentionally stop work; a top-up does not change them. On cancellation, an already atomically admitted model request finishes measurement and settlement, but no new work starts. An unknown outcome retains its hold until authentic reconciliation. Ordinary operator resume does not increase the News limit, and no budget-amendment API is exposed. Default-null News needs no such change: the same task resumes after funding. In task status, balancePause contains requiredCredits and availableCredits; errorCode distinguishes OPERATION_SPENDING_LIMIT from API_KEY_QUOTA_EXCEEDED on failure. Raw provider text is not returned.

A model-service funding wait is different from an insufficient customer balance. With a valid retained wait marker, task status includes recovery: {state: "waiting", reasonCode}: PROVIDER_FUNDING_READ_UNAVAILABLE means funding cannot temporarily be read, while PROVIDER_FUNDING_INSUFFICIENT means waiting for service availability to recover. This wait does not change the task to failed or require another create or a customer top-up. The same task resumes automatically when conditions recover. accounting.capturedCredits and accounting.heldCredits, when available, show actual charged credits and the current outstanding hold from the original receipt, including exposure retained for an unknown effect until evidence resolves it. Absent fields do not mean zero expense. An unknown outcome of an already dispatched request retains its financial protection and does not become a funding wait.

An accepted task retains its input and topic settings from quotation, tariffs, routes and validated results. Changing the current topic does not replace the accepted instructions. When it resumes after a top-up or service restart, completed actions are neither repeated nor charged again. Resuming checks the original order, retained script versions, materials and paid calls. Unknown external outcomes do not authorize a repeat. Historical results and receipts retain their original financial facts; unsupported saved plans cannot execute.

Request fields

Field	Meaning
topic	a topic ID from the public catalog GET /api/config/topics, or your own topic (ct_…); free text and other users’ topics return 400 INVALID_NEWS_TOPIC
period	today, week or month
voiceId, language	a voice from /voices; ru or en
preferences	optional: length_preset is express, standard (default), or detailed; detail_level is telegram, standard (default), or detailed; this_day_in_history is boolean, default false

Any other field returns 400 UNSUPPORTED_API_FIELD. A task answers only to the key that created it; anything else gets 404 TASK_NOT_FOUND.

this_day_in_history: true allows supported historical context within the same spending budget. Historical material is not presented as a current event. Without appropriate support, the optional segment is omitted.

Example

news:quote, news:create

1 · quote

curl -s -X POST https://cast.witqq.dev/api/v1/news/quotes \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "topic": "technology",
  "period": "week",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'

2 · create

curl -s -X POST https://cast.witqq.dev/api/v1/news \
  -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: my-request-001' \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "QUOTE_ID",
  "topic": "technology",
  "period": "week",
  "voiceId": "yandex-speechkit:filipp",
  "language": "ru"
}'