POST/v1/chat

Stream et svar fra assistenten (SSE)

chat

Med flere kopier af API’et bag en load balancer (adressen api.<domain>, 1.62.0) ligger et svar og bufferen med dets hændelser i hukommelsen hos den kopi, der genererer det. Genoptagelse af streamen med Last-Event-ID virker kun på den kopi.

En gentaget anmodning med samme request_id og samtale, der når en anden kopi, efter at svaret er færdigt, modtager det gemte svar (token og done, hændelser nummereret fra 1) uden at stille spørgsmålet igen. En gentaget anmodning, der når en anden kopi, mens svaret stadig genereres, stopper den generering og bygger svaret på ny; der oprettes heller ikke et ekstra spørgsmål. For at genoptage streamen uden en ny generering skal du holde forbindelsen til den samme kopi eller gentage anmodningen efter hændelsen done.

Autentificering

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

Headerparametre

X-View-Asstring
Kun for API-nøgler med rollen admin. Udfører anmodningen som dataprofilen <profile>[:viewer|verifier|editor], fx employee:viewer. Installationsnøglen kan ikke bruge denne header (403).

Cookieparametre

kb_view_asstring
Cookie for tilstanden »View as« i en session. POST /auth/view-as sætter den, og DELETE /auth/view-as fjerner den.

Anmodningens brødtekst

application/json

Objekt: ChatRequest

messagesarray of ChatMessagepåkrævet
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
Hent ikke svaret fra svarcachen (knappen »Get a fresh answer« under et cachet svar). Det nye svar erstatter posten i cachen.
Standard: false
languagestring | null
Svarets sprog: en kode efter ISO 639-1 (de, en, ru, …) for at få svar på det sprog. Med auto eller uden feltet registreres sproget ud fra spørgsmålet. Brugerfladen angiver eksplicit sproget for et forslag på et andet sprog (Starter.language).
scopeChatScope | null
Spørgsmålets afgrænsning: flere samlinger, en kilde, tags og en periode. Afgrænsningens samlinger erstatter collection. En kilde indsnævrer svaret til kildens samling (og kildens egne kort). Tags føjes til tags. Perioden begrænser økonomiske svar til den periode. Du kan kun vælge det, brugeren kan se (samlinger: collections.no_access/collections.not_found; kilde: sources.not_found). Med conversation_id gemmes afgrænsningen i samtalen. Uden feltet gælder samtalens afgrænsning; null eller en tom afgrænsning rydder den.
request_idstring
Spørgsmålets idempotensnøgle. Send den samme nøgle i hvert nyt forsøg på streamen for ét spørgsmål (et nyt forsøg efter en afbrudt forbindelse; her fortsætter Last-Event-ID ikke streamen og logges kun). Et nyt forsøg med nøglen for et svar, der allerede er gemt, opretter ikke et nyt spørgsmål: det gemte resultat sendes igen som én hændelse done (og en hændelse token med teksten), også selvom grænsen for spørgsmål eller credits er opbrugt. Genereres det forrige svar stadig for en klient, der har mistet forbindelsen, stopper genereringen, og svaret genereres på ny.
length ≤ 64
version_ofinteger (int64)
Opretter en ny version af dette spørgsmåls runde i samtalen (question_id fra feedet): et redigeret spørgsmål (ny tekst i messages), et nygenereret svar (den samme tekst, som regel med bypass_cache) eller det samme spørgsmål med en anden quality (fx precise efter et fast-svar). Det forrige par af spørgsmål og svar bevares. Runderne efter det bliver i dets gren og skjules i feedet, mens den nye version er valgt (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Historikken, der bruges til svaret, er den valgte gren frem til denne runde. En versions quality ændrer ikke samtalens indstillinger. Kræver conversation_id; et spørgsmål fra en anden samtale returnerer 404 questions.not_found.
qualitystring
Balancen mellem hastighed og nøjagtighed i søgningen bag resultatet: fast er hurtigere, precise er mere nøjagtig. Standard: precise.
Tilladte værdier: fastprecise

Svar

200Med `stream=true`: `text/event-stream`. Hver hændelse består af linjerne `id: <number>` (hændelsens løbenummer i streamen, startende ved 1) og `data: <JSON>` efterfulgt af en tom linje. Felterne `event:` og `retry:` bruges ikke; hændelsestypen står i feltet `type` (`ChatEvent`).

Med stream=true: text/event-stream. Hver hændelse består af linjerne id: <number> (hændelsens løbenummer i streamen, startende ved 1) og data: <JSON> efterfulgt af en tom linje. Felterne event: og retry: bruges ikke; hændelsestypen står i feltet type (ChatEvent).

Et spørgsmål med request_id besvares uafhængigt af forbindelsen. En afbrudt forbindelse stopper ikke svaret: det gøres færdigt og gemmes i samtalen (i op til 10 minutter). Gentages den samme anmodning (samme request_id og samtale), kobles den på svaret, der er i gang, og med headeren Last-Event-ID modtager den hændelserne efter det nummer, så streamen fortsætter med de samme hændelsesnumre. Kan streamen ikke fortsætte fra det nummer, får den gentagne anmodning streamen fra starten: den første hændelse har så et nummer, der ikke er større end Last-Event-ID, og klienten starter svaret forfra. Er svaret allerede færdigt, og er dets hændelsesbuffer frigivet (efter 3 minutter), sendes det gemte resultat igen (token og done, nummereret fra 1) uden at stille spørgsmålet igen; ellers genereres svaret på ny. Kald POST /v1/chat/cancel for at stoppe et sådant svar. Uden request_id annullerer en afbrudt forbindelse fra klienten svaret.

Efter den første hændelse og så længe svaret er i gang, sender serveren en kommentar : ping hvert 15. sekund; spring den over. Rækkefølgen af hændelser: hændelser stage (fremdrift), meta, sources, data, derefter svarets tekst i hændelser token og til sidst done. Før svarets tekst kan sources og data gentages, og hændelser tool kan forekomme; teksten kan komme som ét token eller i dele. Et svar fra cachen: meta (med cached), sources, data, token, done. En fejl, efter at streamen er startet, kommer som en hændelse error, og streamen lukkes uden done; streamens HTTP-status er altid 200. Efter done kan der komme en hændelse followups med forslag til næste spørgsmål. Ignorér hændelsestyper, du ikke håndterer.

Med stream=false: application/json med en brødtekst AnswerResponse (plus conversation_id).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

text/event-stream

Objekt: ChatEvent

En af

application/json

Objekt: AnswerResponse

answerstringpåkrævet
question_idintegerpåkrævet
querystring
collectionstringpåkrævet
sourcesarray of Sourcepåkrævet
table_queriesarray of TableQuerypåkrævet
datasetsarray of Datasetpåkrævet
chartsarray of ChartSpecpåkrævet
warningsarray of AnswerWarningpåkrævet
timingsTimingspåkrævet
provenancearray of NumberProvenance
emptystring
Tilladte værdier: 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 der blev brugt værktøjer til dette svar: request (eksplicit ønsket); compare, compute, action (ud fra spørgsmålet); needs_calc (der kræves en beregning på tabeller); summary (en oversigt over en samling eller dokumenter); mcp (organisationen har tilsluttet eksterne MCP-servere).
Tilladte værdier: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntitypåkrævet
followupsarray of Followuppåkrævet
conversation_idstring
Kun for POST /v1/chat med en samtale.
answer_idstring
Svarobjektets id.

400Anmodningen er ugyldig: en parameterværdi eller objektets tilstand tillader ikke handlingen (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

404Objektet findes ikke eller er ikke tilgængeligt for dig. API’et bekræfter ikke, at et begrænset objekt findes.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

422Valideringsfejl: brødteksten eller parametrene svarer ikke til skemaet (`detail` er en liste over valideringsfejl), eller en parameterværdi ligger uden for det tilladte interval (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

Retry-After
Antal sekunder, du skal vente, før du prøver anmodningen igen.
RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← answers · API-reference

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"

Afprøv

API-nøgle

Nøglen gemmes kun i denne fanes hukommelse og sendes kun til https://api.sursa.com.

Anmodningerne udføres på din organisations rigtige data.

X-View-As header

Idempotency-Key

Er feltet tomt, genereres en ny nøgle for hver anmodning.

Anmodningens brødtekst (JSON)