Перейти до вмісту
Sursa Developers

POST/v1/chat

Отримувати відповідь асистента потоком (SSE)

chat

Якщо за балансувальником навантаження працює кілька копій API (адреса api.<domain>, 1.62.0), відповідь і буфер її подій зберігаються в пам’яті тієї копії, яка цю відповідь формує. Відновлення потоку з Last-Event-ID працює лише на цій копії.

Повторний запит із тим самим request_id і розмовою, що потрапляє на іншу копію після завершення відповіді, отримує збережену відповідь (token і done, події нумеруються з 1), а запитання повторно не ставиться. Повторний запит, що потрапляє на іншу копію, поки відповідь ще формується, зупиняє це формування й будує відповідь заново; друге запитання при цьому також не створюється. Щоб відновити потік без нового формування, тримайте з’єднання з тією самою копією або повторіть запит після події done.

Автентифікація

Передайте ключ API в заголовку Authorization: Authorization: Bearer <ключ>.

Параметри заголовка

  • X-View-Asstring

    Лише для ключів API з роллю admin. Виконує запит від імені профілю доступу <profile>[:viewer|verifier|editor], наприклад employee:viewer. Ключ інсталяції не може використовувати цей заголовок (403).

Параметри cookie

  • kb_view_asstring

    Cookie режиму «View as» для сесії. Встановлюється через POST /auth/view-as, очищається через DELETE /auth/view-as.

Тіло запиту

application/json

Об’єкт: ChatRequest

  • messagesarray of ChatMessageобов’язково

    items ≥ 1

  • collectionstring

    Типове значення: "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • streamboolean

    Типове значення: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Не брати відповідь із кешу відповідей (кнопка «Get a fresh answer» під відповіддю з кешу). Свіжа відповідь замінює запис у кеші.

    Типове значення: false

  • languagestring | null

    Мова відповіді: код ISO 639-1 (de, en, ru, …), щоб відповісти цією мовою. З auto або без поля мова визначається за запитанням. Інтерфейс явно передає мову підказки іншою мовою (Starter.language).

  • scopeChatScope | null

    Область запитання: кілька колекцій, джерело, теги й період. Колекції області замінюють collection. Джерело звужує відповідь до своєї колекції (і власних карток). Теги додаються до tags. Період обмежує фінансові відповіді цим періодом. Вибрати можна лише те, що бачить користувач (колекції: collections.no_access/collections.not_found; джерело: sources.not_found). З conversation_id область зберігається в розмові. Без поля діє область розмови; null або порожня область очищає її.

  • request_idstring

    Ключ ідемпотентності запитання. Надсилайте той самий ключ у кожному повторі потоку для одного запитання (повтор після розриву з’єднання; тут Last-Event-ID не продовжує потік і лише записується в журнал). Повтор із ключем уже збереженої відповіді не створює другого запитання: збережений результат надсилається знову однією подією done (і token з текстом), навіть якщо ліміт запитань або кредитів вичерпано. Якщо попередня відповідь ще генерується для клієнта, що від’єднався, цю генерацію буде зупинено, а відповідь згенеровано заново.

    length ≤ 64

  • version_ofinteger (int64)

    Створює нову версію репліки цього запитання в розмові (question_id зі стрічки розмови): змінене запитання (новий текст у messages), повторно згенеровану відповідь (той самий текст, зазвичай з bypass_cache) або те саме запитання з іншим quality (наприклад, precise після відповіді fast). Попередня пара запитання й відповіді зберігається. Репліки після неї лишаються в її гілці й приховані зі стрічки розмови, поки вибрано нову версію (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Історія для відповіді — вибрана гілка до цієї репліки. quality версії не змінює налаштувань розмови. Потрібен conversation_id; запитання з іншої розмови повертає 404 questions.not_found.

  • qualitystring

    Баланс між швидкістю та точністю пошуку, на якому ґрунтується результат: fast — швидше, precise — точніше. Типово — precise.

    Допустимі значення: fastprecise

Відповіді

200З `stream=true`: `text/event-stream`. Кожна подія складається з рядків `id: <number>` (порядковий номер події в потоці, починаючи з 1) і `data: <JSON>`, після яких іде порожній рядок. Поля `event:` і `retry:` не використовуються; тип події — у полі `type` (`ChatEvent`).

З stream=true: text/event-stream. Кожна подія складається з рядків id: <number> (порядковий номер події в потоці, починаючи з 1) і data: <JSON>, після яких іде порожній рядок. Поля event: і retry: не використовуються; тип події — у полі type (ChatEvent).

Відповідь на запитання з request_id формується незалежно від з’єднання. Розрив з’єднання не зупиняє відповідь: її буде завершено й збережено в розмові (протягом щонайбільше 10 хвилин). Повтор того самого запиту (той самий request_id і розмова) приєднується до відповіді, що формується, а із заголовком Last-Event-ID отримує події після цього номера, тож потік продовжується з тими самими номерами подій. Якщо потік не може продовжитися з цього номера, повторний запит отримує потік від початку: тоді перша подія має номер, не більший за Last-Event-ID, і клієнт починає відповідь заново. Якщо відповідь уже завершено й буфер її подій звільнено (через 3 хвилини), збережений результат надсилається знову (token і done, нумерація з 1), а запитання повторно не ставиться; інакше відповідь формується заново. Щоб зупинити таку відповідь, викличте POST /v1/chat/cancel. Без request_id розрив з’єднання з боку клієнта скасовує відповідь.

Після першої події, поки відповідь формується, сервер кожні 15 секунд надсилає коментар : ping; пропускайте його. Порядок подій: події stage (перебіг), meta, sources, data, потім текст відповіді в подіях token, потім done. До тексту відповіді sources і data можуть повторюватися, а також можуть з’являтися події tool; текст може надійти одним token або частинами. Відповідь із кешу: meta (з cached), sources, data, token, done. Помилка після початку потоку надходить як подія error, і потік закривається без done; статус HTTP потоку завжди 200. Після done може надійти подія followups із підказками наступних запитань. Ігноруйте типи подій, які ви не обробляєте.

З stream=false: application/json з тілом AnswerResponse (а також conversation_id).

Заголовки відповіді

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

text/event-stream

Об’єкт: ChatEvent

Одне з

application/json

Об’єкт: AnswerResponse

  • answerstringобов’язково
  • question_idintegerобов’язково
  • querystring
  • collectionstringобов’язково
  • sourcesarray of Sourceобов’язково
  • table_queriesarray of TableQueryобов’язково
  • datasetsarray of Datasetобов’язково
  • chartsarray of ChartSpecобов’язково
  • warningsarray of AnswerWarningобов’язково
  • timingsTimingsобов’язково
  • provenancearray of NumberProvenance
  • emptystring

    Допустимі значення: no_hitsrestrictedguardrailno_data_for_period

  • basisAnswerBasis
  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • guardrailGuardrailVerdict
  • verified_onlyboolean
  • cachedboolean
  • cache_hitAnswerCacheHit
  • out_of_scopeAnswerOutOfScope
  • attachmentsarray of Attachment
  • export_errorstring
  • toolsstring | null

    Чому для цієї відповіді використано інструменти: request (явно запитано); compare, compute, action (за змістом запитання); needs_calc (потрібен розрахунок за таблицями); summary (огляд колекції або документів); mcp (організація підключила зовнішні сервери MCP).

    Допустимі значення: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityобов’язково
  • followupsarray of Followupобов’язково
  • conversation_idstring

    Лише для POST /v1/chat з розмовою.

  • answer_idstring

    ID об’єкта відповіді.

400Неправильний запит: значення параметра або стан об’єкта не дозволяє виконати дію (`detail` — повідомлення).

Заголовки відповіді

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

application/json

Об’єкт: Error

401Облікові дані не надіслано (ні cookie сесії, ні ключа API) або ключ не знайдено.

Заголовки відповіді

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

application/json

Об’єкт: Error

403Дію не дозволено: роль не має достатніх прав, немає доступу до колекції чи картки, запит виконується в режимі «View as» або організацію призупинено чи видалено (`detail` — об’єкт із `code: org_suspended | org_deleted`).

Заголовки відповіді

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

application/json

Об’єкт: Error

404Об’єкт не існує або недоступний вам. API не підтверджує існування об’єкта з обмеженим доступом.

Заголовки відповіді

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

application/json

Об’єкт: Error

422Помилка валідації: тіло або параметри не відповідають схемі (`detail` — список помилок валідації) або значення параметра виходить за допустимі межі (`detail` — повідомлення).

Заголовки відповіді

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

application/json

Об’єкт: Error

429Забагато запитів (`api.rate_limited`), квоту організації на хвилину, день або місяць вичерпано (`api.quota_exceeded`; `error.details` містить `quota`, `limit` і `reset_at`), досягнуто ліміту організації або сервіс відповідей зайнятий (`answers.engine_busy`). Зачекайте стільки, скільки вказано в заголовку `Retry-After`.

Заголовки відповіді

  • Retry-After

    Кількість секунд, які слід зачекати перед повторним запитом.

  • RateLimit-Policy

    Чинні ліміти у форматі чернетки IETF draft-ietf-httpapi-ratelimit-headers: елементи через кому "<name>";q=<quota>;w=<window in seconds>. key — частота запитів ключа API (квота — це сплеск, вікно — час, за який квота повністю відновлюється; для сесії цей елемент називається user, без облікових даних — ip); minute, day і month — квоти організації на календарну хвилину, день і місяць за UTC.

  • RateLimit

    Скільки лишилося за кожним лімітом із RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Ліміт найсуворішого елемента в RateLimit-Policy (того, за яким лишилося найменше запитів).

  • X-RateLimit-Remaining

    Скільки запитів лишилося за найсуворішим лімітом.

  • X-RateLimit-Reset

    Кількість секунд до скидання найсуворішого ліміту.

application/json

Об’єкт: Error

Коди помилок

Коди, які ця операція може повернути в error.code, крім загальних кодів будь-якого запиту.

Безпечні повтори

Надсилайте заголовок Idempotency-Key (наприклад, UUID) з кожним POST і PATCH. Повтор із тим самим ключем протягом 24 годин повертає збережену відповідь, а не виконує запит знову.

Ліміти частоти

Відповіді містять заголовки RateLimit і RateLimit-Policy, а також давніші X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset. Відповідь 429 містить Retry-After у секундах: зачекайте й повторіть запит.

← answers · Довідник API