POST/v1/chat

Gauti asistento atsakymą srautu (SSE)

chat

Kai už apkrovos balansavimo įrenginio veikia kelios API kopijos (adresas api.<domain>, 1.62.0), atsakymas ir jo įvykių buferis laikomi kopijos, kuri jį generuoja, atmintyje. Srautą su Last-Event-ID galima tęsti tik toje kopijoje.

Pakartotinė užklausa su tuo pačiu request_id ir pokalbiu, pasiekusi kitą kopiją jau baigus atsakymą, gauna išsaugotą atsakymą (token ir done, įvykiai numeruojami nuo 1), klausimas iš naujo neužduodamas. Pakartotinė užklausa, pasiekusi kitą kopiją, kol atsakymas dar generuojamas, sustabdo tą generavimą ir atsakymą sudaro iš naujo; antras klausimas taip pat nesukuriamas. Norėdami tęsti srautą be naujo generavimo, išlaikykite ryšį su ta pačia kopija arba pakartokite užklausą po įvykio done.

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Antraštės parametrai

X-View-Asstring
Tik API raktams su vaidmeniu admin. Užklausa vykdoma duomenų profilio <profile>[:viewer|verifier|editor] vardu, pvz., employee:viewer. Diegimo raktas šios antraštės naudoti negali (403).

Slapuko parametrai

kb_view_asstring
Režimo „View as“ (žiūrėti kaip) sesijos slapukas. POST /auth/view-as jį nustato, o DELETE /auth/view-as išvalo.

Užklausos turinys

application/json

Objektas: ChatRequest

messagesarray of ChatMessageprivalomas
items ≥ 1
collectionstring
Numatytoji reikšmė: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Numatytoji reikšmė: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Neimti atsakymo iš atsakymų podėlio (mygtukas „Get a fresh answer“ po atsakymu iš podėlio). Naujas atsakymas pakeičia įrašą podėlyje.
Numatytoji reikšmė: false
languagestring | null
Atsakymo kalba: ISO 639-1 kodas (de, en, ru, …), kad atsakymas būtų ta kalba. Su auto arba be lauko kalba nustatoma pagal klausimą. Sąsaja kitos kalbos pasiūlymo kalbą perduoda aiškiai (Starter.language).
scopeChatScope | null
Klausimo sritis: keli rinkiniai, šaltinis, žymos ir laikotarpis. Srities rinkiniai pakeičia collection. Šaltinis susiaurina atsakymą iki savo rinkinio (ir savo kortelių). Žymos pridedamos prie tags. Laikotarpis apriboja finansinius atsakymus tuo laikotarpiu. Galima pasirinkti tik tai, ką naudotojas mato (rinkiniai: collections.no_access/collections.not_found; šaltinis: sources.not_found). Su conversation_id sritis išsaugoma pokalbyje. Be lauko taikoma pokalbio sritis; null arba tuščia sritis ją išvalo.
request_idstring
Klausimo idempotentiškumo raktas. Siųskite tą patį raktą kiekviename vieno klausimo srauto pakartojime (pakartojime po ryšio nutrūkimo; čia Last-Event-ID srauto netęsia ir tik įrašomas į žurnalą). Pakartojimas su jau išsaugoto atsakymo raktu nesukuria antro klausimo: išsaugotas rezultatas išsiunčiamas iš naujo kaip vienas įvykis done (ir token su tekstu), net jei klausimų ar kreditų limitas išnaudotas. Jei ankstesnis atsakymas atsijungusiam klientui dar generuojamas, šis generavimas sustabdomas ir atsakymas generuojamas iš naujo.
length ≤ 64
version_ofinteger (int64)
Sukuria naują šio klausimo replikos versiją pokalbyje (question_id iš pokalbio juostos): redaguotą klausimą (naujas tekstas messages), iš naujo sugeneruotą atsakymą (tas pats tekstas, paprastai su bypass_cache) arba tą patį klausimą su kitu quality (pavyzdžiui, precise po fast atsakymo). Ankstesnė klausimo ir atsakymo pora išsaugoma. Po jos einančios replikos lieka jos šakoje ir juostoje nerodomos, kol pasirinkta nauja versija (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Atsakymui naudojama istorija – pasirinkta šaka iki šios replikos. Versijos quality pokalbio nustatymų nekeičia. Reikia conversation_id; klausimas iš kito pokalbio grąžina 404 questions.not_found.
qualitystring
Paieškos, iš kurios gautas rezultatas, greičio ir tikslumo pusiausvyra: fast – greičiau, precise – tiksliau. Numatytoji reikšmė: precise.
Leidžiamos reikšmės: fastprecise

Atsakai

200Su `stream=true`: `text/event-stream`. Kiekvieną įvykį sudaro eilutės `id: <number>` (įvykio eilės numeris sraute, pradedant nuo 1) ir `data: <JSON>`, po jų – tuščia eilutė. Laukai `event:` ir `retry:` nenaudojami; įvykio tipas nurodomas lauke `type` (`ChatEvent`).

Su stream=true: text/event-stream. Kiekvieną įvykį sudaro eilutės id: <number> (įvykio eilės numeris sraute, pradedant nuo 1) ir data: <JSON>, po jų – tuščia eilutė. Laukai event: ir retry: nenaudojami; įvykio tipas nurodomas lauke type (ChatEvent).

Klausimas su request_id atsakomas nepriklausomai nuo ryšio. Atsijungimas atsakymo nesustabdo: jis užbaigiamas ir išsaugomas pokalbyje (iki 10 minučių). Pakartojus tą pačią užklausą (tas pats request_id ir pokalbis), prisijungiama prie vykdomo atsakymo, o su antrašte Last-Event-ID gaunami po to numerio einantys įvykiai, todėl srautas tęsiasi su tais pačiais įvykių numeriais. Jei srauto nuo to numerio tęsti neįmanoma, pakartotinė užklausa gauna srautą nuo pradžių: tada pirmojo įvykio numeris yra ne didesnis už Last-Event-ID, ir klientas atsakymą pradeda iš naujo. Jei atsakymas jau baigtas ir jo įvykių buferis atlaisvintas (po 3 minučių), išsaugotas rezultatas siunčiamas dar kartą (token ir done, numeruojami nuo 1), klausimas iš naujo neužduodamas; kitaip atsakymas generuojamas iš naujo. Norėdami sustabdyti tokį atsakymą, iškvieskite POST /v1/chat/cancel. Be request_id kliento atsijungimas atšaukia atsakymą.

Po pirmojo įvykio, kol atsakymas vykdomas, serveris kas 15 sekundžių siunčia komentarą : ping; jį praleiskite. Įvykių tvarka: įvykiai stage (eiga), meta, sources, data, tada atsakymo tekstas įvykiuose token, tada done. Prieš atsakymo tekstą sources ir data gali kartotis ir gali atsirasti įvykių tool; tekstas gali ateiti vienu token arba dalimis. Atsakymas iš podėlio: meta (su cached), sources, data, token, done. Klaida, įvykusi srautui jau prasidėjus, ateina kaip įvykis error, o srautas užsidaro be done; srauto HTTP būsena visada 200. Po done gali ateiti įvykis followups su siūlomais tolesniais klausimais. Neapdorojamų įvykių tipų nepaisykite.

Su stream=false: application/json su turiniu AnswerResponse (ir conversation_id).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

text/event-stream

Objektas: ChatEvent

Viena iš

application/json

Objektas: AnswerResponse

answerstringprivalomas
question_idintegerprivalomas
querystring
collectionstringprivalomas
sourcesarray of Sourceprivalomas
table_queriesarray of TableQueryprivalomas
datasetsarray of Datasetprivalomas
chartsarray of ChartSpecprivalomas
warningsarray of AnswerWarningprivalomas
timingsTimingsprivalomas
provenancearray of NumberProvenance
emptystring
Leidžiamos reikšmės: 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
Kodėl šiam atsakymui naudoti įrankiai: request (paprašyta aiškiai); compare, compute, action (pagal klausimą); needs_calc (reikia skaičiavimų su lentelėmis); summary (rinkinio ar dokumentų apžvalga); mcp (organizacija prijungė išorinius MCP serverius).
Leidžiamos reikšmės: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityprivalomas
followupsarray of Followupprivalomas
conversation_idstring
Tik POST /v1/chat su pokalbiu.
answer_idstring
Atsakymo objekto ID.

400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

404Objekto nėra arba jis jums nepasiekiamas. API nepatvirtina, kad ribotos prieigos objektas egzistuoja.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

Retry-After
Kiek sekundžių palaukti prieš kartojant užklausą.
RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← answers · API žinynas

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"

Išbandyti

API raktas

Raktas laikomas tik šio skirtuko atmintyje ir siunčiamas tik į https://api.sursa.com.

Užklausos vykdomos su tikrais jūsų organizacijos duomenimis.

X-View-As header

Idempotency-Key

Jei laukas tuščias, kiekvienai užklausai sugeneruojamas naujas raktas.

Užklausos turinys (JSON)