POST/v1/chat

Strøm et svar fra assistenten (SSE)

chat

Med flere kopier av API-et bak en lastbalanserer (adressen api.<domain>, 1.62.0) ligger et svar og bufferen med hendelsene i minnet til kopien som genererer det. Gjenopptakelse av strømmen med Last-Event-ID fungerer bare på den kopien.

En gjentatt forespørsel med samme request_id og samtale som når en annen kopi etter at svaret er ferdig, får det lagrede svaret (token og done, hendelser nummerert fra 1) uten at spørsmålet stilles på nytt. En gjentatt forespørsel som når en annen kopi mens svaret fortsatt genereres, stopper den genereringen og bygger svaret på nytt; det opprettes heller ikke noe spørsmål nummer to. For å gjenoppta strømmen uten ny generering beholder du tilkoblingen til samme kopi eller gjentar forespørselen etter hendelsen done.

Autentisering

Send en API-nøkkel i headeren Authorization: Authorization: Bearer <nøkkel>.

Headerparametere

X-View-Asstring
Bare for API-nøkler med rollen admin. Utfører forespørselen som dataprofilen <profile>[:viewer|verifier|editor], for eksempel employee:viewer. Installasjonsnøkkelen kan ikke bruke denne headeren (403).

Parametere i informasjonskapsler

kb_view_asstring
Informasjonskapsel for modusen «View as» (vis som) i en økt. POST /auth/view-as setter den, og DELETE /auth/view-as fjerner den.

Forespørselens brødtekst

application/json

Objekt: ChatRequest

messagesarray of ChatMessageobligatorisk
items ≥ 1
collectionstring
Standard: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Standard: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Ikke hent svaret fra svarbufferen (knappen «Get a fresh answer» (hent et nytt svar) under et bufret svar). Det nye svaret erstatter den bufrede oppføringen.
Standard: false
languagestring | null
Svarspråk: en kode etter ISO 639-1 (de, en, ru, …) for å svare på det språket. Med auto eller uten feltet gjenkjennes språket fra spørsmålet. Grensesnittet sender språket til et forslag på et annet språk eksplisitt (Starter.language).
scopeChatScope | null
Spørsmålets omfang: flere samlinger, en kilde, tagger og en periode. Samlingene i omfanget erstatter collection. En kilde begrenser svaret til kildens samling (og kildens egne kort). Taggene legges til i tags. Perioden begrenser økonomiske svar til den perioden. Du kan bare velge det brukeren kan se (samlinger: collections.no_access/collections.not_found; kilde: sources.not_found). Med conversation_id lagres omfanget i samtalen. Uten feltet gjelder samtalens omfang; null eller et tomt omfang fjerner det.
request_idstring
Spørsmålets idempotensnøkkel. Send den samme nøkkelen i hvert nytt forsøk på strømmen for ett spørsmål (et nytt forsøk etter et brudd; her fortsetter ikke Last-Event-ID strømmen og blir bare logget). Et nytt forsøk med nøkkelen til et svar som allerede er lagret, oppretter ikke et nytt spørsmål: det lagrede resultatet sendes på nytt som én hendelse done (og en token med teksten), selv om grensen for spørsmål eller kreditter er brukt opp. Hvis det forrige svaret fortsatt lages for en klient som har mistet tilkoblingen, stoppes det, og svaret lages på nytt.
length ≤ 64
version_ofinteger (int64)
Oppretter en ny versjon av denne spørsmålsrunden i samtalen (question_id fra feeden): et redigert spørsmål (ny tekst i messages), et nytt svar (den samme teksten, vanligvis med bypass_cache) eller det samme spørsmålet med en annen quality (for eksempel precise etter et fast-svar). Det forrige paret av spørsmål og svar beholdes. Rundene etter det blir værende i grenen og skjules i feeden mens den nye versjonen er valgt (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Historikken som brukes til svaret, er den valgte grenen fram til denne runden. quality for en versjon endrer ikke samtalens innstillinger. Krever conversation_id; et spørsmål fra en annen samtale returnerer 404 questions.not_found.
qualitystring
Balansen mellom hastighet og nøyaktighet i søket bak resultatet: fast er raskere, precise er mer nøyaktig. Standard: precise.
Tillatte verdier: fastprecise

Svar

200Med `stream=true`: `text/event-stream`. Hver hendelse består av linjene `id: <number>` (hendelsens løpenummer i strømmen, fra 1) og `data: <JSON>`, etterfulgt av en tom linje. Feltene `event:` og `retry:` brukes ikke; hendelsestypen står i feltet `type` (`ChatEvent`).

Med stream=true: text/event-stream. Hver hendelse består av linjene id: <number> (hendelsens løpenummer i strømmen, fra 1) og data: <JSON>, etterfulgt av en tom linje. Feltene event: og retry: brukes ikke; hendelsestypen står i feltet type (ChatEvent).

Et spørsmål med request_id besvares uavhengig av tilkoblingen. Et brudd i tilkoblingen stopper ikke svaret: det fullføres og lagres i samtalen (i opptil 10 minutter). Når den samme forespørselen gjentas (samme request_id og samtale), kobles den til svaret som pågår, og med headeren Last-Event-ID får den hendelsene etter det nummeret, slik at strømmen fortsetter med de samme hendelsesnumrene. Hvis strømmen ikke kan fortsette fra det nummeret, får den gjentatte forespørselen strømmen fra begynnelsen: den første hendelsen har da et nummer som ikke er større enn Last-Event-ID, og klienten begynner på svaret på nytt. Hvis svaret allerede er ferdig og hendelsesbufferen er frigitt (etter 3 minutter), sendes det lagrede resultatet på nytt (token og done, nummerert fra 1) uten at spørsmålet stilles på nytt; ellers genereres svaret på nytt. For å stoppe et slikt svar kaller du POST /v1/chat/cancel. Uten request_id avbryter et brudd i klientens tilkobling svaret.

Etter den første hendelsen, mens svaret pågår, sender serveren kommentaren : ping hvert 15. sekund; hopp over den. Rekkefølgen på hendelsene: stage-hendelser (fremdrift), meta, sources, data, deretter teksten i svaret i token-hendelser, deretter done. Før teksten i svaret kan sources og data gjentas, og tool-hendelser kan forekomme; teksten kan komme som én token eller i deler. Et bufret svar: meta (med cached), sources, data, token, done. En feil etter at strømmen har startet, kommer som en error-hendelse, og strømmen lukkes uten done; HTTP-statusen for strømmen er alltid 200. Etter done kan en followups-hendelse med foreslåtte neste spørsmål komme. Ignorer hendelsestyper du ikke håndterer.

Med stream=false: application/json med brødteksten AnswerResponse (pluss conversation_id).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

text/event-stream

Objekt: ChatEvent

Én av

application/json

Objekt: AnswerResponse

answerstringobligatorisk
question_idintegerobligatorisk
querystring
collectionstringobligatorisk
sourcesarray of Sourceobligatorisk
table_queriesarray of TableQueryobligatorisk
datasetsarray of Datasetobligatorisk
chartsarray of ChartSpecobligatorisk
warningsarray of AnswerWarningobligatorisk
timingsTimingsobligatorisk
provenancearray of NumberProvenance
emptystring
Tillatte verdier: 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
Hvorfor verktøy ble brukt til dette svaret: request (bedt om eksplisitt); compare, compute, action (ut fra spørsmålet); needs_calc (det trengs en beregning over tabeller); summary (en oversikt over en samling eller dokumenter); mcp (organisasjonen har koblet til eksterne MCP-servere).
Tillatte verdier: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityobligatorisk
followupsarray of Followupobligatorisk
conversation_idstring
Bare for POST /v1/chat med en samtale.
answer_idstring
Svarobjektets ID.

400Forespørselen er ugyldig: en parameterverdi eller objektets tilstand tillater ikke handlingen (`detail` er en melding).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

401Ingen påloggingsinformasjon ble sendt (verken øktinformasjonskapsel eller API-nøkkel), eller nøkkelen ble ikke funnet.

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

403Handlingen er ikke tillatt: rollen er utilstrekkelig, det finnes ingen tilgang til samlingen eller kortet, forespørselen kjører i modusen «View as», eller organisasjonen er suspendert eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

404Objektet finnes ikke eller er ikke tilgjengelig for deg. API-et bekrefter ikke at et objekt med begrenset tilgang finnes.

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

422Valideringsfeil: brødteksten eller parameterne samsvarer ikke med skjemaet (`detail` er en liste over valideringsfeil), eller en parameterverdi er utenfor tillatt område (`detail` er en melding).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

429For mange forespørsler (`api.rate_limited`), organisasjonens kvote for minuttet, døgnet eller måneden er brukt opp (`api.quota_exceeded`; `error.details` inneholder `quota`, `limit` og `reset_at`), organisasjonens grense er nådd, eller svartjenesten er opptatt (`answers.engine_busy`). Vent så lenge som headeren `Retry-After` angir.

Headere i svaret

Retry-After
Antall sekunder du skal vente før du prøver forespørselen på nytt.
RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

Feilkoder

Kodene denne operasjonen kan returnere i error.code, i tillegg til de generelle kodene for alle forespørsler.

Trygge nye forsøk

Send en Idempotency-Key-header (for eksempel en UUID) med hver POST og PATCH. Et nytt forsøk med samme nøkkel innen 24 timer returnerer det lagrede svaret i stedet for å kjøre forespørselen på nytt.

Hastighetsgrenser

Svarene har headerne RateLimit og RateLimit-Policy og de eldre X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og prøv på nytt.

← answers · API-referanse

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"

Prøv

API-nøkkel

Nøkkelen lagres bare i minnet til denne fanen og sendes bare til https://api.sursa.com.

Forespørslene utføres på de faktiske dataene i organisasjonen din.

X-View-As header

Idempotency-Key

Når feltet er tomt, genereres en ny nøkkel for hver forespørsel.

Forespørselens brødtekst (JSON)