POST/v1/chat

Antwoord van de assistent streamen (SSE)

chat

Met meerdere kopieën van de API achter een load balancer (het adres api.<domain>, 1.62.0) leven een antwoord en de buffer met zijn events in het geheugen van de kopie die het genereert. De stream hervatten met Last-Event-ID werkt alleen op die kopie.

Een herhaald request met dezelfde request_id en hetzelfde gesprek dat na afloop van het antwoord bij een andere kopie terechtkomt, krijgt het opgeslagen antwoord (token en done, events genummerd vanaf 1) zonder dat de vraag opnieuw wordt gesteld. Een herhaald request dat bij een andere kopie terechtkomt terwijl het antwoord nog wordt gegenereerd, stopt die generatie en bouwt het antwoord opnieuw op; ook dan ontstaat er geen tweede vraag. Om de stream zonder nieuwe generatie te hervatten, houd je de verbinding met dezelfde kopie aan of herhaal je het request na het event done.

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Headerparameters

X-View-Asstring
Alleen voor API-sleutels met de rol admin. Voert het request uit als het dataprofiel <profile>[:viewer|verifier|editor], bijvoorbeeld employee:viewer. De installatiesleutel kan deze header niet gebruiken (403).

Cookieparameters

kb_view_asstring
Cookie van de modus “View as” voor een sessie. POST /auth/view-as zet hem en DELETE /auth/view-as wist hem.

Request-body

application/json

Object: ChatRequest

messagesarray of ChatMessageverplicht
items ≥ 1
collectionstring
Standaard: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Standaard: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Het antwoord niet uit de antwoordcache halen (de knop “Get a fresh answer” – een nieuw antwoord – onder een antwoord uit de cache). Het nieuwe antwoord vervangt het item in de cache.
Standaard: false
languagestring | null
Taal van het antwoord: een ISO 639-1-code (de, en, ru, …) om in die taal te antwoorden. Met auto of zonder het veld wordt de taal uit de vraag afgeleid. De interface geeft de taal van een suggestie in een andere taal expliciet mee (Starter.language).
scopeChatScope | null
Bereik van de vraag: meerdere collecties, een bron, tags en een periode. De collecties van het bereik vervangen collection. Een bron beperkt het antwoord tot haar collectie (en haar eigen kaarten). Tags worden aan tags toegevoegd. De periode beperkt financiële antwoorden tot die periode. Je kunt alleen kiezen wat de gebruiker kan zien (collecties: collections.no_access/collections.not_found; bron: sources.not_found). Met conversation_id wordt het bereik in het gesprek opgeslagen. Zonder het veld geldt het bereik van het gesprek; null of een leeg bereik wist het.
request_idstring
Idempotentiesleutel van de vraag. Stuur dezelfde sleutel bij elke nieuwe poging van de stream voor één vraag (een nieuwe poging na een verbroken verbinding; hier zet Last-Event-ID de stream niet voort en wordt het alleen gelogd). Een nieuwe poging met de sleutel van een antwoord dat al is opgeslagen, maakt geen tweede vraag aan: het opgeslagen resultaat wordt opnieuw verstuurd als één event done (en een token met de tekst), ook als de limiet voor vragen of credits op is. Wordt het vorige antwoord nog gegenereerd voor een client die de verbinding verloor, dan stopt die generatie en wordt het antwoord opnieuw gegenereerd.
length ≤ 64
version_ofinteger (int64)
Maakt een nieuwe versie van de beurt van deze vraag in het gesprek (question_id uit het gespreksverloop): een bewerkte vraag (nieuwe tekst in messages), een opnieuw gegenereerd antwoord (dezelfde tekst, meestal met bypass_cache) of dezelfde vraag met een andere quality (bijvoorbeeld precise na een antwoord met fast). Het vorige paar van vraag en antwoord blijft bewaard. De beurten daarna blijven in de tak ervan en zijn verborgen in het gespreksverloop zolang de nieuwe versie is geselecteerd (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). De geschiedenis voor het antwoord is de geselecteerde tak tot en met deze beurt. De quality van een versie verandert de instellingen van het gesprek niet. Vereist conversation_id; een vraag uit een ander gesprek geeft 404 questions.not_found.
qualitystring
Balans tussen snelheid en nauwkeurigheid van het zoeken achter het resultaat: fast is sneller, precise is nauwkeuriger. Standaard: precise.
Toegestane waarden: fastprecise

Responses

200Met `stream=true`: `text/event-stream`. Elk event bestaat uit de regels `id: <number>` (het volgnummer van het event in de stream, vanaf 1) en `data: <JSON>`, gevolgd door een lege regel. De velden `event:` en `retry:` worden niet gebruikt; het eventtype staat in het veld `type` (`ChatEvent`).

Met stream=true: text/event-stream. Elk event bestaat uit de regels id: <number> (het volgnummer van het event in de stream, vanaf 1) en data: <JSON>, gevolgd door een lege regel. De velden event: en retry: worden niet gebruikt; het eventtype staat in het veld type (ChatEvent).

Een vraag met request_id wordt los van de verbinding beantwoord. Een verbroken verbinding stopt het antwoord niet: het wordt afgemaakt en in het gesprek opgeslagen (gedurende maximaal 10 minuten). Hetzelfde request herhalen (dezelfde request_id en hetzelfde gesprek) koppelt aan het lopende antwoord, en met de header Last-Event-ID krijgt het de events na dat nummer, zodat de stream doorloopt met dezelfde eventnummers. Als de stream niet vanaf dat nummer kan doorgaan, krijgt het herhaalde request de stream vanaf het begin: het eerste event heeft dan een nummer dat niet groter is dan Last-Event-ID, en de client begint opnieuw aan het antwoord. Als het antwoord al klaar is en de buffer met zijn events is vrijgegeven (na 3 minuten), wordt het opgeslagen resultaat opnieuw verstuurd (token en done, genummerd vanaf 1) zonder dat de vraag opnieuw wordt gesteld; anders wordt het antwoord opnieuw gegenereerd. Om zo’n antwoord te stoppen, roep je POST /v1/chat/cancel aan. Zonder request_id annuleert een verbroken verbinding van de client het antwoord.

Na het eerste event, zolang het antwoord loopt, stuurt de server elke 15 seconden een commentaarregel : ping; sla die over. Volgorde van de events: events stage (voortgang), meta, sources, data, dan de tekst van het antwoord in events token, dan done. Vóór de tekst van het antwoord kunnen sources en data herhaald worden en kunnen events tool verschijnen; de tekst kan als één token of in delen binnenkomen. Een antwoord uit de cache: meta (met cached), sources, data, token, done. Een fout nadat de stream is begonnen, komt binnen als event error, en de stream sluit zonder done; de HTTP-status van de stream is altijd 200. Na done kan een event followups met voorgestelde vervolgvragen binnenkomen. Negeer eventtypes die je niet verwerkt.

Met stream=false: application/json met een body AnswerResponse (plus conversation_id).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

text/event-stream

Object: ChatEvent

Eén van

application/json

Object: AnswerResponse

answerstringverplicht
question_idintegerverplicht
querystring
collectionstringverplicht
sourcesarray of Sourceverplicht
table_queriesarray of TableQueryverplicht
datasetsarray of Datasetverplicht
chartsarray of ChartSpecverplicht
warningsarray of AnswerWarningverplicht
timingsTimingsverplicht
provenancearray of NumberProvenance
emptystring
Toegestane waarden: 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
Waarom er voor dit antwoord tools zijn gebruikt: request (expliciet gevraagd); compare, compute, action (op basis van de vraag); needs_calc (er is een berekening over tabellen nodig); summary (een overzicht van een collectie of documenten); mcp (de organisatie heeft externe MCP-servers gekoppeld).
Toegestane waarden: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityverplicht
followupsarray of Followupverplicht
conversation_idstring
Alleen voor POST /v1/chat met een gesprek.
answer_idstring
ID van het antwoordobject.

400Het request is ongeldig: een parameterwaarde of de toestand van het object staat de actie niet toe (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

404Het object bestaat niet of is niet voor jou beschikbaar. De API bevestigt niet dat een afgeschermd object bestaat.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

422Validatiefout: de body of de parameters komen niet overeen met het schema (`detail` is een lijst met validatiefouten), of een parameterwaarde valt buiten het bereik (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

Retry-After
Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.
RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← answers · API-referentie

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"

Uitproberen

API-sleutel

De sleutel blijft in het geheugen van dit tabblad en wordt alleen naar https://api.sursa.com gestuurd.

Requests werken met de echte gegevens van je organisatie.

X-View-As header

Idempotency-Key

Is dit veld leeg, dan wordt voor elk request een nieuwe sleutel gegenereerd.

Request-body (JSON)