POST/v1/chat

Transmetre en temps real una resposta de l’assistent (SSE)

chat

Amb diverses còpies de l’API darrere d’un balancejador de càrrega (l’adreça api.<domain>, 1.62.0), una resposta i la memòria intermèdia dels seus esdeveniments són a la memòria de la còpia que la genera. Reprendre el flux amb Last-Event-ID només funciona en aquella còpia.

Una sol·licitud repetida amb el mateix request_id i la mateixa conversa que arriba a una altra còpia quan la resposta ja ha acabat rep la resposta desada (token i done, amb els esdeveniments numerats des d’1) sense tornar a fer la pregunta. Una sol·licitud repetida que arriba a una altra còpia mentre la resposta encara s’està generant atura aquella generació i construeix la resposta de nou; tampoc no es crea una segona pregunta. Per reprendre el flux sense una generació nova, mantingueu la connexió amb la mateixa còpia o repetiu la sol·licitud després de l’esdeveniment done.

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de capçalera

X-View-Asstring
Només per a claus d’API amb el rol admin. Fa la sol·licitud com el perfil de dades <profile>[:viewer|verifier|editor], per exemple employee:viewer. La clau d’instal·lació no pot fer servir aquesta capçalera (403).

Paràmetres de galeta

kb_view_asstring
Galeta del mode «View as» per a una sessió. POST /auth/view-as l’estableix i DELETE /auth/view-as l’esborra.

Cos de la sol·licitud

application/json

Objecte: ChatRequest

messagesarray of ChatMessageobligatori
items ≥ 1
collectionstring
Per defecte: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Per defecte: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
No pren la resposta de la memòria cau de respostes (el botó «Get a fresh answer» —obtenir una resposta nova— sota una resposta de la memòria cau). La resposta nova substitueix l’element de la memòria cau.
Per defecte: false
languagestring | null
Llengua de la resposta: un codi ISO 639-1 (de, en, ru, …) per respondre en aquesta llengua. Amb auto o sense el camp, la llengua es detecta a partir de la pregunta. La interfície passa explícitament la llengua d’un suggeriment en una altra llengua (Starter.language).
scopeChatScope | null
Abast de la pregunta: diverses col·leccions, una font, etiquetes i un període. Les col·leccions de l’abast substitueixen collection. Una font restringeix la resposta a la seva col·lecció (i a les seves pròpies entrades). Les etiquetes s’afegeixen a tags. El període limita les respostes financeres a aquest període. Només es pot seleccionar el que l’usuari pot veure (col·leccions: collections.no_access/collections.not_found; font: sources.not_found). Amb conversation_id, l’abast es desa a la conversa. Sense el camp, s’aplica l’abast de la conversa; null o un abast buit l’esborra.
request_idstring
Clau d’idempotència de la pregunta. Envieu la mateixa clau en cada reintent del flux per a una mateixa pregunta (un reintent després d’una desconnexió; aquí Last-Event-ID no continua el flux i només es registra). Un reintent amb la clau d’una resposta que ja s’ha desat no crea una segona pregunta: el resultat desat es torna a enviar com un sol esdeveniment done (i un token amb el text), encara que s’hagi esgotat el límit de preguntes o de crèdits. Si la resposta anterior encara s’està generant per a un client desconnectat, aquesta generació s’atura i la resposta es torna a generar.
length ≤ 64
version_ofinteger (int64)
Crea una versió nova del torn d’aquesta pregunta a la conversa (question_id de l’historial): una pregunta editada (text nou a messages), una resposta regenerada (el mateix text, normalment amb bypass_cache) o la mateixa pregunta amb un altre valor de quality (per exemple, precise després d’una resposta fast). Es conserva la parella anterior de pregunta i resposta. Els torns posteriors es queden a la seva branca i s’amaguen de l’historial mentre la versió nova està seleccionada (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). L’historial que es fa servir per a la resposta és la branca seleccionada fins a aquest torn. El valor de quality d’una versió no canvia la configuració de la conversa. Requereix conversation_id; una pregunta d’una altra conversa retorna 404 questions.not_found.
qualitystring
Equilibri entre la velocitat i la precisió de la cerca en què es basa el resultat: fast és més ràpida, precise és més precisa. Per defecte: precise.
Valors permesos: fastprecise

Respostes

200Amb `stream=true`: `text/event-stream`. Cada esdeveniment consta de les línies `id: <number>` (el número d’ordre de l’esdeveniment al flux, començant per 1) i `data: <JSON>`, seguides d’una línia buida. Els camps `event:` i `retry:` no s’utilitzen; el tipus d’esdeveniment és al camp `type` (`ChatEvent`).

Amb stream=true: text/event-stream. Cada esdeveniment consta de les línies id: <number> (el número d’ordre de l’esdeveniment al flux, començant per 1) i data: <JSON>, seguides d’una línia buida. Els camps event: i retry: no s’utilitzen; el tipus d’esdeveniment és al camp type (ChatEvent).

Una pregunta amb request_id es respon independentment de la connexió. Una desconnexió no atura la resposta: es completa i es desa a la conversa (durant un màxim de 10 minuts). Repetir la mateixa sol·licitud (el mateix request_id i la mateixa conversa) s’uneix a la resposta en curs i, amb la capçalera Last-Event-ID, rep els esdeveniments posteriors a aquest número, de manera que el flux continua amb els mateixos números d’esdeveniment. Si el flux no pot continuar des d’aquest número, la sol·licitud repetida rep el flux des del començament: aleshores el primer esdeveniment té un número que no és més gran que Last-Event-ID, i el client torna a començar la resposta. Si la resposta ja ha acabat i la memòria intermèdia dels seus esdeveniments s’ha alliberat (al cap de 3 minuts), el resultat desat s’envia de nou (token i done, numerats des d’1) sense tornar a fer la pregunta; si no, la resposta es genera de nou. Per aturar una resposta d’aquest tipus, crideu POST /v1/chat/cancel. Sense request_id, una desconnexió del client cancel·la la resposta.

Després del primer esdeveniment, mentre la resposta està en curs, el servidor envia un comentari : ping cada 15 segons; ometeu-lo. Ordre dels esdeveniments: esdeveniments stage (progrés), meta, sources, data, després el text de la resposta en esdeveniments token i, finalment, done. Abans del text de la resposta, sources i data es poden repetir i poden aparèixer esdeveniments tool; el text pot arribar en un sol token o en parts. Una resposta de la memòria cau: meta (amb cached), sources, data, token, done. Un error després que el flux hagi començat arriba com a esdeveniment error, i el flux es tanca sense done; l’estat HTTP del flux sempre és 200. Després de done, pot arribar un esdeveniment followups amb les preguntes següents suggerides. Ignoreu els tipus d’esdeveniment que no tracteu.

Amb stream=false: application/json amb un cos AnswerResponse (més conversation_id).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

text/event-stream

Objecte: ChatEvent

Un de

application/json

Objecte: AnswerResponse

answerstringobligatori
question_idintegerobligatori
querystring
collectionstringobligatori
sourcesarray of Sourceobligatori
table_queriesarray of TableQueryobligatori
datasetsarray of Datasetobligatori
chartsarray of ChartSpecobligatori
warningsarray of AnswerWarningobligatori
timingsTimingsobligatori
provenancearray of NumberProvenance
emptystring
Valors permesos: 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
Per què s’han fet servir eines per a aquesta resposta: request (s’ha demanat explícitament); compare, compute, action (segons la pregunta); needs_calc (cal un càlcul sobre taules); summary (una visió general d’una col·lecció o de documents); mcp (l’organització ha connectat servidors MCP externs).
Valors permesos: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityobligatori
followupsarray of Followupobligatori
conversation_idstring
Només per a POST /v1/chat amb una conversa.
answer_idstring
ID de l’objecte de la resposta.

400La sol·licitud no és vàlida: el valor d’un paràmetre o l’estat de l’objecte no permeten l’acció (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

404L’objecte no existeix o no està disponible per a vós. L’API no confirma que existeixi un objecte restringit.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

422Error de validació: el cos o els paràmetres no coincideixen amb l’esquema (`detail` és una llista d’errors de validació), o el valor d’un paràmetre és fora de l’interval permès (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

Retry-After
Nombre de segons que cal esperar abans de reintentar la sol·licitud.
RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Reintents segurs

Envieu una capçalera Idempotency-Key (per exemple, un UUID) amb cada POST i PATCH. Un reintent amb la mateixa clau en un termini de 24 hores retorna la resposta desada en lloc de tornar a executar la sol·licitud.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← answers · Referència de l’API

curl -X POST 'https://api.sursa.com/v1/chat' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"How do I request a refund?"}],"collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Provar

Clau d’API

La clau es queda a la memòria d’aquesta pestanya i només s’envia a https://api.sursa.com.

Les sol·licituds actuen sobre les dades reals de la vostra organització.

X-View-As header

Idempotency-Key

Si és buit, es genera una clau nova per a cada sol·licitud.

Cos de la sol·licitud (JSON)