Перейти к содержанию
Sursa для разработчиков

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 режима «Смотреть как» для сессии. 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

    Не брать ответ из кеша ответов (кнопка «Получить свежий ответ» под ответом из кеша). Свежий ответ заменяет запись в кеше.

    По умолчанию: 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Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`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