Ir al contenido
Sursa Developers

POST/v1/chat

Transmitir una respuesta del asistente (SSE)

chat

Con varias copias de la API detrás de un balanceador de carga (la dirección api.<domain>, 1.62.0), una respuesta y el búfer de sus eventos están en la memoria de la copia que la genera. Reanudar el flujo con Last-Event-ID solo funciona en esa copia.

Una solicitud repetida con el mismo request_id y la misma conversación que llega a otra copia después de que la respuesta haya terminado recibe la respuesta guardada (token y done, con los eventos numerados desde 1) sin volver a hacer la pregunta. Una solicitud repetida que llega a otra copia mientras la respuesta aún se está generando detiene esa generación y construye la respuesta de nuevo; tampoco en este caso se crea una segunda pregunta. Para reanudar el flujo sin una generación nueva, mantenga la conexión con la misma copia o repita la solicitud después del evento done.

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de encabezado

  • X-View-Asstring

    Solo para claves de API con el rol admin. Ejecuta la solicitud como el perfil de datos <profile>[:viewer|verifier|editor], por ejemplo employee:viewer. La clave de instalación no puede usar este encabezado (403).

Parámetros de cookie

  • kb_view_asstring

    Cookie del modo «View as» para una sesión. POST /auth/view-as la establece y DELETE /auth/view-as la elimina.

Cuerpo de la solicitud

application/json

Objeto: ChatRequest

  • messagesarray of ChatMessageobligatorio

    items ≥ 1

  • collectionstring

    Predeterminado: "default"

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

    items ≤ 50

  • streamboolean

    Predeterminado: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    No tomar la respuesta de la caché de respuestas (el botón «Get a fresh answer» —obtener una respuesta nueva— bajo una respuesta en caché). La respuesta nueva sustituye la entrada en caché.

    Predeterminado: false

  • languagestring | null

    Idioma de la respuesta: un código ISO 639-1 (de, en, ru, …) para responder en ese idioma. Con auto o sin el campo, el idioma se detecta a partir de la pregunta. La interfaz envía de forma explícita el idioma de una sugerencia en otro idioma (Starter.language).

  • scopeChatScope | null

    Alcance de la pregunta: varias colecciones, una fuente, etiquetas y un período. Las colecciones del alcance sustituyen a collection. Una fuente limita la respuesta a su colección (y a sus propias tarjetas). Las etiquetas se añaden a tags. El período limita las respuestas financieras a ese período. Solo se puede seleccionar lo que el usuario puede ver (colecciones: collections.no_access/collections.not_found; fuente: sources.not_found). Con conversation_id, el alcance se guarda en la conversación. Sin el campo, se aplica el alcance de la conversación; null o un alcance vacío lo borra.

  • request_idstring

    Clave de idempotencia de la pregunta. Envíe la misma clave en cada reintento del flujo de una misma pregunta (un reintento tras una desconexión; aquí Last-Event-ID no continúa el flujo y solo se registra). Un reintento con la clave de una respuesta ya guardada no crea una segunda pregunta: el resultado guardado se envía de nuevo como un único evento done (y un token con el texto), aunque se haya agotado el límite de preguntas o de créditos. Si la respuesta anterior todavía se está generando para un cliente desconectado, esa generación se detiene y la respuesta se genera de nuevo.

    length ≤ 64

  • version_ofinteger (int64)

    Crea una versión nueva del turno de esta pregunta en la conversación (question_id del historial de la conversación): una pregunta editada (texto nuevo en messages), una respuesta regenerada (el mismo texto, normalmente con bypass_cache) o la misma pregunta con otro quality (por ejemplo, precise después de una respuesta fast). Se conserva el par anterior de pregunta y respuesta. Los turnos posteriores permanecen en su rama y se ocultan del historial mientras está seleccionada la versión nueva (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). El historial que se usa para la respuesta es la rama seleccionada hasta este turno. El quality de una versión no cambia la configuración de la conversación. Requiere conversation_id; una pregunta de otra conversación devuelve 404 questions.not_found.

  • qualitystring

    Equilibrio entre velocidad y precisión de la búsqueda en la que se basa el resultado: fast es más rápido, precise es más preciso. Predeterminado: precise.

    Valores permitidos: fastprecise

Respuestas

200Con `stream=true`: `text/event-stream`. Cada evento consta de las líneas `id: <number>` (el número de orden del evento en el flujo, empezando por 1) y `data: <JSON>`, seguidas de una línea vacía. Los campos `event:` y `retry:` no se usan; el tipo de evento está en el campo `type` (`ChatEvent`).

Con stream=true: text/event-stream. Cada evento consta de las líneas id: <number> (el número de orden del evento en el flujo, empezando por 1) y data: <JSON>, seguidas de una línea vacía. Los campos event: y retry: no se usan; el tipo de evento está en el campo type (ChatEvent).

Una pregunta con request_id se responde con independencia de la conexión. Una desconexión no detiene la respuesta: se completa y se guarda en la conversación (durante un máximo de 10 minutos). Una repetición de la misma solicitud (el mismo request_id y la misma conversación) se une a la respuesta en curso y, con el encabezado Last-Event-ID, recibe los eventos posteriores a ese número, de modo que el flujo continúa con los mismos números de evento. Si el flujo no puede continuar desde ese número, la solicitud repetida recibe el flujo desde el principio: el primer evento tiene entonces un número no mayor que Last-Event-ID, y el cliente empieza la respuesta de nuevo. Si la respuesta ya ha terminado y su búfer de eventos se ha liberado (al cabo de 3 minutos), se vuelve a enviar el resultado guardado (token y done, numerados desde 1) sin volver a hacer la pregunta; en otro caso, la respuesta se genera de nuevo. Para detener una respuesta así, llame a POST /v1/chat/cancel. Sin request_id, una desconexión del cliente cancela la respuesta.

Tras el primer evento, mientras la respuesta está en curso, el servidor envía un comentario : ping cada 15 segundos; ignórelo. Orden de los eventos: eventos stage (progreso), meta, sources, data, después el texto de la respuesta en eventos token y, por último, done. Antes del texto de la respuesta, sources y data pueden repetirse y pueden aparecer eventos tool; el texto puede llegar en un solo token o en partes. Una respuesta en caché: meta (con cached), sources, data, token, done. Un error después de que el flujo haya empezado llega como evento error, y el flujo se cierra sin done; el estado HTTP del flujo es siempre 200. Después de done puede llegar un evento followups con preguntas siguientes sugeridas. Ignore los tipos de evento que no gestione.

Con stream=false: application/json con un cuerpo AnswerResponse (más conversation_id).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

text/event-stream

Objeto: ChatEvent

Uno de

application/json

Objeto: AnswerResponse

  • answerstringobligatorio
  • question_idintegerobligatorio
  • querystring
  • collectionstringobligatorio
  • sourcesarray of Sourceobligatorio
  • table_queriesarray of TableQueryobligatorio
  • datasetsarray of Datasetobligatorio
  • chartsarray of ChartSpecobligatorio
  • warningsarray of AnswerWarningobligatorio
  • timingsTimingsobligatorio
  • 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 qué se usaron herramientas en esta respuesta: request (se pidieron de forma explícita); compare, compute, action (según la pregunta); needs_calc (hace falta un cálculo sobre tablas); summary (una visión general de una colección o de documentos); mcp (la organización ha conectado servidores MCP externos).

    Valores permitidos: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityobligatorio
  • followupsarray of Followupobligatorio
  • conversation_idstring

    Solo en POST /v1/chat con una conversación.

  • answer_idstring

    ID del objeto de la respuesta.

400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

404El objeto no existe o no está disponible para usted. La API no confirma la existencia de un objeto restringido.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

  • Retry-After

    Número de segundos que hay que esperar antes de reintentar la solicitud.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← answers · Referencia de la API