POST/v1/chat

Tok odgovora asistenta (SSE)

chat

Kad iza uravnoteživača opterećenja radi više kopija API-ja (adresa api.<domain>, 1.62.0), odgovor i međuspremnik njegovih događaja nalaze se u memoriji kopije koja ga stvara. Nastavak toka s Last-Event-ID radi samo na toj kopiji.

Ponovljeni zahtjev s istim request_id i razgovorom koji stigne do druge kopije nakon što je odgovor završen dobiva spremljeni odgovor (token i done, događaji numerirani od 1) bez ponovnog postavljanja pitanja. Ponovljeni zahtjev koji stigne do druge kopije dok se odgovor još stvara zaustavlja to stvaranje i izrađuje odgovor ispočetka; ni tada se ne stvara drugo pitanje. Da biste nastavili tok bez novog stvaranja odgovora, zadržite vezu s istom kopijom ili ponovite zahtjev nakon događaja done.

Autentifikacija

Pošaljite API ključ u zaglavlju Authorization: Authorization: Bearer <ključ>.

Parametri zaglavlja

X-View-Asstring
Samo za API ključeve s ulogom admin. Izvodi zahtjev kao podatkovni profil <profile>[:viewer|verifier|editor], na primjer employee:viewer. Ključ instalacije ne može koristiti ovo zaglavlje (403).

Parametri kolačića

kb_view_asstring
Kolačić načina „View as” za sesiju. Postavlja ga POST /auth/view-as, a briše DELETE /auth/view-as.

Tijelo zahtjeva

application/json

Objekt: ChatRequest

messagesarray of ChatMessageobavezno
items ≥ 1
collectionstring
Zadano: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Zadano: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Odgovor se ne uzima iz predmemorije odgovora (gumb „Get a fresh answer” ispod odgovora iz predmemorije). Novi odgovor zamjenjuje zapis u predmemoriji.
Zadano: false
languagestring | null
Jezik odgovora: kod ISO 639-1 (de, en, ru, …) za odgovor na tom jeziku. Uz auto ili bez polja jezik se određuje prema pitanju. Sučelje izričito prosljeđuje jezik prijedloga na drugom jeziku (Starter.language).
scopeChatScope | null
Opseg pitanja: više zbirki, izvor, oznake i razdoblje. Zbirke iz opsega zamjenjuju collection. Izvor sužava odgovor na svoju zbirku (i vlastite kartice). Oznake se dodaju u tags. Razdoblje ograničava financijske odgovore na to razdoblje. Možete odabrati samo ono što korisnik vidi (zbirke: collections.no_access/collections.not_found; izvor: sources.not_found). Uz conversation_id opseg se sprema u razgovor. Bez polja vrijedi opseg razgovora; null ili prazan opseg ga briše.
request_idstring
Ključ idempotentnosti pitanja. Šaljite isti ključ u svakom ponovnom pokušaju toka za jedno pitanje (ponovni pokušaj nakon prekida veze; ovdje Last-Event-ID ne nastavlja tok i samo se bilježi). Ponovni pokušaj s ključem odgovora koji je već spremljen ne stvara drugo pitanje: spremljeni rezultat ponovno se šalje kao jedan događaj done (i token s tekstom), čak i ako je ograničenje pitanja ili kredita iscrpljeno. Ako se prethodni odgovor za klijenta s prekinutom vezom još stvara, to se stvaranje zaustavlja i odgovor se stvara iznova.
length ≤ 64
version_ofinteger (int64)
Stvara novu verziju replike ovog pitanja u razgovoru (question_id iz povijesti razgovora): uređeno pitanje (novi tekst u messages), ponovno stvoren odgovor (isti tekst, obično uz bypass_cache) ili isto pitanje s drugim quality (na primjer precise nakon odgovora fast). Prethodni par pitanja i odgovora čuva se. Replike nakon njega ostaju u njegovoj grani i skrivene su iz povijesti razgovora dok je odabrana nova verzija (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Povijest koja se koristi za odgovor je odabrana grana do ove replike. quality verzije ne mijenja postavke razgovora. Zahtijeva conversation_id; pitanje iz drugog razgovora vraća 404 questions.not_found.
qualitystring
Omjer brzine i točnosti pretraživanja na kojem se temelji rezultat: fast je brži, precise je točniji. Zadano: precise.
Dopuštene vrijednosti: fastprecise

Odgovori

200S `stream=true`: `text/event-stream`. Svaki se događaj sastoji od redaka `id: <number>` (redni broj događaja u toku, počevši od 1) i `data: <JSON>`, nakon kojih slijedi prazan redak. Polja `event:` i `retry:` ne koriste se; vrsta događaja nalazi se u polju `type` (`ChatEvent`).

S stream=true: text/event-stream. Svaki se događaj sastoji od redaka id: <number> (redni broj događaja u toku, počevši od 1) i data: <JSON>, nakon kojih slijedi prazan redak. Polja event: i retry: ne koriste se; vrsta događaja nalazi se u polju type (ChatEvent).

Na pitanje s request_id odgovara se neovisno o vezi. Prekid veze ne zaustavlja odgovor: on se dovršava i sprema u razgovor (do 10 minuta). Ponavljanje istog zahtjeva (isti request_id i razgovor) priključuje se odgovoru u tijeku, a sa zaglavljem Last-Event-ID prima događaje nakon tog broja, pa se tok nastavlja s istim brojevima događaja. Ako se tok ne može nastaviti od tog broja, ponovljeni zahtjev dobiva tok od početka: prvi događaj tada ima broj koji nije veći od Last-Event-ID, a klijent započinje odgovor ispočetka. Ako je odgovor već završen i međuspremnik njegovih događaja oslobođen (nakon 3 minute), spremljeni rezultat šalje se ponovno (token i done, numerirani od 1) bez ponovnog postavljanja pitanja; inače se odgovor stvara ispočetka. Da biste zaustavili takav odgovor, pozovite POST /v1/chat/cancel. Bez request_id prekid veze s klijentom otkazuje odgovor.

Nakon prvog događaja, dok je odgovor u tijeku, poslužitelj svakih 15 sekundi šalje komentar : ping; preskočite ga. Redoslijed događaja: događaji stage (napredak), meta, sources, data, zatim tekst odgovora u događajima token, zatim done. Prije teksta odgovora sources i data mogu se ponoviti i mogu se pojaviti događaji tool; tekst može stići kao jedan token ili u dijelovima. Odgovor iz predmemorije: meta (s cached), sources, data, token, done. Pogreška nakon početka toka stiže kao događaj error, a tok se zatvara bez done; HTTP status toka uvijek je 200. Nakon done može stići događaj followups s predloženim sljedećim pitanjima. Zanemarite vrste događaja koje ne obrađujete.

S stream=false: application/json s tijelom AnswerResponse (uz conversation_id).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

text/event-stream

Objekt: ChatEvent

Jedno od

application/json

Objekt: AnswerResponse

answerstringobavezno
question_idintegerobavezno
querystring
collectionstringobavezno
sourcesarray of Sourceobavezno
table_queriesarray of TableQueryobavezno
datasetsarray of Datasetobavezno
chartsarray of ChartSpecobavezno
warningsarray of AnswerWarningobavezno
timingsTimingsobavezno
provenancearray of NumberProvenance
emptystring
Dopuštene vrijednosti: 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
Zašto su za ovaj odgovor korišteni alati: request (izričito zatraženo); compare, compute, action (na temelju pitanja); needs_calc (potreban je izračun nad tablicama); summary (pregled zbirke ili dokumenata); mcp (organizacija je povezala vanjske MCP poslužitelje).
Dopuštene vrijednosti: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityobavezno
followupsarray of Followupobavezno
conversation_idstring
Samo za POST /v1/chat s razgovorom.
answer_idstring
ID objekta odgovora.

400Zahtjev nije valjan: vrijednost parametra ili stanje objekta ne dopušta radnju (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

401Vjerodajnice nisu poslane (ni kolačić sesije ni API ključ) ili ključ nije pronađen.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

403Radnja nije dopuštena: uloga nije dovoljna, nema pristupa zbirci ili kartici, zahtjev se izvodi u načinu „View as” ili je organizacija suspendirana ili izbrisana (`detail` je objekt s `code: org_suspended | org_deleted`).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

404Objekt ne postoji ili vam nije dostupan. API ne potvrđuje postojanje ograničenog objekta.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

422Pogreška provjere valjanosti: tijelo ili parametri ne odgovaraju shemi (`detail` je popis pogrešaka provjere valjanosti) ili je vrijednost parametra izvan raspona (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

429Previše zahtjeva (`api.rate_limited`), kvota organizacije za minutu, dan ili mjesec je potrošena (`api.quota_exceeded`; `error.details` sadrži `quota`, `limit` i `reset_at`), dosegnuto je ograničenje organizacije ili je usluga odgovora zauzeta (`answers.engine_busy`). Pričekajte vrijeme navedeno u zaglavlju `Retry-After`.

Zaglavlja odgovora

Retry-After
Broj sekundi koje treba pričekati prije ponovnog pokušaja zahtjeva.
RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

Kodovi pogrešaka

Kodovi koje ova operacija može vratiti u error.code, uz opće kodove svakog zahtjeva.

Sigurni ponovni pokušaji

Uz svaki POST i PATCH pošaljite zaglavlje Idempotency-Key (na primjer UUID). Ponovni pokušaj s istim ključem unutar 24 sata vraća spremljeni odgovor umjesto da ponovno izvrši zahtjev.

Ograničenja učestalosti

Odgovori sadrže zaglavlja RateLimit i RateLimit-Policy te ranija zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odgovor 429 sadrži zaglavlje Retry-After u sekundama: pričekajte i pokušajte ponovno.

← answers · Referenca API-ja

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"

Isprobajte

API ključ

Ključ ostaje u memoriji ove kartice preglednika i šalje se samo na https://api.sursa.com.

Zahtjevi djeluju na stvarne podatke vaše organizacije.

X-View-As header

Idempotency-Key

Ako je polje prazno, za svaki se zahtjev stvara novi ključ.

Tijelo zahtjeva (JSON)