Pular para o conteúdo
Sursa Developers

POST/v1/chat

Transmitir uma resposta do assistente (SSE)

chat

Com várias cópias da API atrás de um balanceador de carga (o endereço api.<domain>, versão 1.62.0), uma resposta e o buffer dos eventos dela ficam na memória da cópia que a gera. Retomar o stream com Last-Event-ID só funciona nessa cópia.

Uma requisição repetida com o mesmo request_id e a mesma conversa que chega a outra cópia depois de a resposta terminar recebe a resposta salva (token e done, eventos numerados a partir de 1) sem fazer a pergunta de novo. Uma requisição repetida que chega a outra cópia enquanto a resposta ainda está sendo gerada interrompe essa geração e monta a resposta do zero; também não se cria uma segunda pergunta. Para retomar o stream sem nova geração, mantenha a conexão com a mesma cópia ou repita a requisição depois do evento done.

Autenticação

Envie uma chave de API no cabeçalho Authorization: Authorization: Bearer <chave>.

Parâmetros de cabeçalho

  • X-View-Asstring

    Só para chaves de API com a função admin. Faz a requisição como o perfil de dados <profile>[:viewer|verifier|editor], por exemplo, employee:viewer. A chave de instalação não pode usar este cabeçalho (403).

Parâmetros de cookie

  • kb_view_asstring

    Cookie do modo “View as” (ver a base como um perfil de dados a vê) de uma sessão. POST /auth/view-as o define e DELETE /auth/view-as o remove.

Corpo da requisição

application/json

Objeto: ChatRequest

  • messagesarray of ChatMessageobrigatório

    items ≥ 1

  • collectionstring

    Padrão: "default"

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

    items ≤ 50

  • streamboolean

    Padrão: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Não usar a resposta do cache de respostas (o botão “Get a fresh answer” (obter uma resposta nova) sob uma resposta do cache). A resposta nova substitui a entrada do cache.

    Padrão: false

  • languagestring | null

    Idioma da resposta: um código ISO 639-1 (de, en, ru, …) para responder nesse idioma. Com auto ou sem o campo, o idioma é detectado a partir da pergunta. A interface passa explicitamente o idioma de uma sugestão em outro idioma (Starter.language).

  • scopeChatScope | null

    Abrangência da pergunta: várias coleções, uma fonte, etiquetas e um período. As coleções da abrangência substituem collection. Uma fonte restringe a resposta à coleção dela (e aos cartões dela). As etiquetas são acrescentadas a tags. O período limita as respostas financeiras a esse período. Só é possível selecionar o que o usuário pode ver (coleções: collections.no_access/collections.not_found; fonte: sources.not_found). Com conversation_id, a abrangência é salva na conversa. Sem o campo, vale a abrangência da conversa; null ou uma abrangência vazia a limpa.

  • request_idstring

    Chave de idempotência da pergunta. Envie a mesma chave em cada nova tentativa do stream de uma pergunta (uma nova tentativa após uma desconexão; aqui Last-Event-ID não continua o stream e só é registrado). Uma nova tentativa com a chave de uma resposta já salva não cria uma segunda pergunta: o resultado salvo é enviado de novo como um único evento done (e um token com o texto), mesmo que o limite de perguntas ou de créditos tenha se esgotado. Se a resposta anterior ainda estiver sendo gerada para um cliente desconectado, essa geração para e a resposta é gerada de novo.

    length ≤ 64

  • version_ofinteger (int64)

    Cria uma nova versão do turno desta pergunta na conversa (question_id do histórico da conversa): uma pergunta editada (novo texto em messages), uma resposta gerada de novo (o mesmo texto, em geral com bypass_cache) ou a mesma pergunta com outro quality (por exemplo, precise depois de uma resposta fast). O par anterior de pergunta e resposta é mantido. Os turnos posteriores ficam no ramo dele e são ocultados do histórico enquanto a nova versão estiver selecionada (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). O histórico usado para a resposta é o ramo selecionado até este turno. O quality de uma versão não altera as configurações da conversa. Requer conversation_id; uma pergunta de outra conversa retorna 404 questions.not_found.

  • qualitystring

    Equilíbrio entre velocidade e precisão da busca por trás do resultado: fast é mais rápido, precise é mais preciso. Padrão: precise.

    Valores permitidos: fastprecise

Respostas

200Com `stream=true`: `text/event-stream`. Cada evento é formado pelas linhas `id: <number>` (o número sequencial do evento no stream, a partir de 1) e `data: <JSON>`, seguidas de uma linha vazia. Os campos `event:` e `retry:` não são usados; o tipo do evento fica no campo `type` (`ChatEvent`).

Com stream=true: text/event-stream. Cada evento é formado pelas linhas id: <number> (o número sequencial do evento no stream, a partir de 1) e data: <JSON>, seguidas de uma linha vazia. Os campos event: e retry: não são usados; o tipo do evento fica no campo type (ChatEvent).

Uma pergunta com request_id é respondida independentemente da conexão. Uma desconexão não interrompe a resposta: ela é concluída e salva na conversa (por até 10 minutos). Repetir a mesma requisição (o mesmo request_id e a mesma conversa) conecta à resposta em andamento e, com o cabeçalho Last-Event-ID, recebe os eventos posteriores a esse número, de modo que o stream continua com os mesmos números de evento. Se o stream não puder continuar a partir desse número, a requisição repetida recebe o stream desde o início: o primeiro evento tem então um número não maior que Last-Event-ID, e o cliente recomeça a resposta. Se a resposta já terminou e o buffer de eventos dela foi liberado (após 3 minutos), o resultado salvo é enviado de novo (token e done, numerados a partir de 1) sem fazer a pergunta de novo; caso contrário, a resposta é gerada do zero. Para interromper essa resposta, chame POST /v1/chat/cancel. Sem request_id, uma desconexão do cliente cancela a resposta.

Depois do primeiro evento, enquanto a resposta está em andamento, o servidor envia um comentário : ping a cada 15 segundos; ignore-o. Ordem dos eventos: eventos stage (progresso), meta, sources, data, depois o texto da resposta em eventos token e, por fim, done. Antes do texto da resposta, sources e data podem se repetir, e eventos tool podem aparecer; o texto pode chegar como um único token ou em partes. Uma resposta em cache: meta (com cached), sources, data, token, done. Um erro depois que o stream começou chega como um evento error, e o stream é fechado sem done; o status HTTP do stream é sempre 200. Depois de done, pode chegar um evento followups com sugestões de próximas perguntas. Ignore os tipos de evento que você não trata.

Com stream=false: application/json com um corpo AnswerResponse (mais conversation_id).

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

text/event-stream

Objeto: ChatEvent

Um de

application/json

Objeto: AnswerResponse

  • answerstringobrigatório
  • question_idintegerobrigatório
  • querystring
  • collectionstringobrigatório
  • sourcesarray of Sourceobrigatório
  • table_queriesarray of TableQueryobrigatório
  • datasetsarray of Datasetobrigatório
  • chartsarray of ChartSpecobrigatório
  • warningsarray of AnswerWarningobrigatório
  • timingsTimingsobrigatório
  • provenancearray of NumberProvenance
  • emptystring

    Valores permitidos: 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

    Por que foram usadas ferramentas nesta resposta: request (pedido explicitamente); compare, compute, action (com base na pergunta); needs_calc (é preciso um cálculo sobre tabelas); summary (uma visão geral de uma coleção ou de documentos); mcp (a organização conectou servidores MCP externos).

    Valores permitidos: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityobrigatório
  • followupsarray of Followupobrigatório
  • conversation_idstring

    Só para POST /v1/chat com uma conversa.

  • answer_idstring

    ID do objeto da resposta.

400A requisição é inválida: o valor de um parâmetro ou o estado do objeto não permite a ação (`detail` é uma mensagem).

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

401Nenhuma credencial foi enviada (nem cookie de sessão nem chave de API), ou a chave não foi encontrada.

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

403A ação não é permitida: a função é insuficiente, não há acesso à coleção ou ao cartão, a requisição é executada no modo “View as” ou a organização está suspensa ou excluída (`detail` é um objeto com `code: org_suspended | org_deleted`).

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

404O objeto não existe ou não está disponível para você. A API não confirma que um objeto restrito existe.

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

422Erro de validação: o corpo ou os parâmetros não correspondem ao esquema (`detail` é uma lista de erros de validação), ou o valor de um parâmetro está fora do intervalo (`detail` é uma mensagem).

Cabeçalhos da resposta

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

429Requisições demais (`api.rate_limited`), a cota da organização para o minuto, o dia ou o mês se esgotou (`api.quota_exceeded`; `error.details` contém `quota`, `limit` e `reset_at`), o limite da organização foi atingido ou o serviço de respostas está ocupado (`answers.engine_busy`). Aguarde o tempo indicado no cabeçalho `Retry-After`.

Cabeçalhos da resposta

  • Retry-After

    Número de segundos a esperar antes de tentar a requisição novamente.

  • RateLimit-Policy

    Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.

  • RateLimit

    O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).

  • X-RateLimit-Remaining

    Requisições restantes no limite mais restritivo.

  • X-RateLimit-Reset

    Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

Códigos de erro

Códigos que este endpoint pode retornar em error.code, além dos códigos gerais de qualquer requisição.

Novas tentativas seguras

Envie um cabeçalho Idempotency-Key (por exemplo, um UUID) em cada POST e PATCH. Uma nova tentativa com a mesma chave em até 24 horas retorna a resposta salva, em vez de executar a requisição de novo.

Limites de taxa

As respostas trazem os cabeçalhos RateLimit e RateLimit-Policy e os anteriores X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta 429 traz Retry-After em segundos: aguarde e tente de novo.

← answers · Referência da API