POST/v1/chat

Straumēt asistenta atbildi (SSE)

chat

Ja aiz slodzes līdzsvarotāja ir vairākas API kopijas (adrese api.<domain>, 1.62.0), atbilde un tās notikumu buferis atrodas tās kopijas atmiņā, kas atbildi ģenerē. Straumes turpināšana ar Last-Event-ID darbojas tikai šajā kopijā.

Atkārtots pieprasījums ar to pašu request_id un sarunu, kas pēc atbildes pabeigšanas nonāk citā kopijā, saņem saglabāto atbildi (token un done, notikumi numurēti no 1), jautājumu neuzdodot vēlreiz. Atkārtots pieprasījums, kas nonāk citā kopijā, kamēr atbilde vēl tiek ģenerēta, aptur šo ģenerēšanu un veido atbildi no jauna; arī tad otrs jautājums netiek izveidots. Lai turpinātu straumi bez jaunas ģenerēšanas, saglabājiet savienojumu ar to pašu kopiju vai atkārtojiet pieprasījumu pēc notikuma done.

Autentifikācija

Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.

Galvenes parametri

X-View-Asstring
Tikai API atslēgām ar lomu admin. Izpilda pieprasījumu datu profila <profile>[:viewer|verifier|editor] vārdā, piemēram, employee:viewer. Instalācijas atslēga šo galveni lietot nevar (403).

Sīkdatņu parametri

kb_view_asstring
Režīma „View as“ (skatīt kā) sīkdatne sesijai. POST /auth/view-as to iestata, un DELETE /auth/view-as to notīra.

Pieprasījuma saturs

application/json

Objekts: ChatRequest

messagesarray of ChatMessageobligāts
items ≥ 1
collectionstring
Noklusējums: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Noklusējums: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Neņemt atbildi no atbilžu kešatmiņas (poga „Get a fresh answer“ (saņemt jaunu atbildi) zem kešatmiņā saglabātas atbildes). Jaunā atbilde aizstāj kešatmiņā saglabāto ierakstu.
Noklusējums: false
languagestring | null
Atbildes valoda: ISO 639-1 kods (de, en, ru, …), lai atbildētu šajā valodā. Ar auto vai bez lauka valodu nosaka pēc jautājuma. Ieteikumam citā valodā saskarne tā valodu nodod skaidri (Starter.language).
scopeChatScope | null
Jautājuma joma: vairākas kolekcijas, avots, birkas un periods. Jomas kolekcijas aizstāj collection. Avots sašaurina atbildi līdz tā kolekcijai (un tā paša kartītēm). Birkas tiek pievienotas laukam tags. Periods ierobežo finanšu atbildes ar šo periodu. Var izvēlēties tikai to, ko lietotājs redz (kolekcijas: collections.no_access/collections.not_found; avots: sources.not_found). Ar conversation_id joma tiek saglabāta sarunā. Bez lauka darbojas sarunas joma; null vai tukša joma to notīra.
request_idstring
Jautājuma idempotences atslēga. Sūtiet to pašu atslēgu katrā straumes atkārtojumā vienam jautājumam (atkārtojums pēc savienojuma pārtraukuma; šeit Last-Event-ID straumi neturpina un tiek tikai ierakstīts žurnālā). Atkārtojums ar jau saglabātas atbildes atslēgu neizveido otru jautājumu: saglabātais rezultāts tiek nosūtīts vēlreiz kā viens notikums done (un token ar tekstu), pat ja jautājumu vai kredītu limits ir izsmelts. Ja iepriekšējā atbilde atvienotam klientam vēl tiek ģenerēta, šī ģenerēšana apstājas, un atbilde tiek ģenerēta no jauna.
length ≤ 64
version_ofinteger (int64)
Izveido šī jautājuma replikas jaunu versiju sarunā (question_id no plūsmas): rediģētu jautājumu (jauns teksts laukā messages), no jauna ģenerētu atbildi (tas pats teksts, parasti ar bypass_cache) vai to pašu jautājumu ar citu quality (piemēram, precise pēc fast atbildes). Iepriekšējais jautājuma un atbildes pāris tiek saglabāts. Replikas pēc tā paliek tā zarā un ir paslēptas no plūsmas, kamēr izvēlēta jaunā versija (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Atbildei izmantotā vēsture ir izvēlētais zars līdz šai replikai. Versijas quality nemaina sarunas iestatījumus. Nepieciešams conversation_id; jautājums no citas sarunas atgriež 404 questions.not_found.
qualitystring
Ātruma un precizitātes līdzsvars meklēšanā, uz kuras balstās rezultāts: fast ir ātrāks, precise – precīzāks. Noklusējums: precise.
Atļautās vērtības: fastprecise

Atbildes

200Ar `stream=true`: `text/event-stream`. Katrs notikums sastāv no rindām `id: <number>` (notikuma kārtas numurs straumē, sākot no 1) un `data: <JSON>`, kam seko tukša rinda. Lauki `event:` un `retry:` netiek lietoti; notikuma tips ir laukā `type` (`ChatEvent`).

Ar stream=true: text/event-stream. Katrs notikums sastāv no rindām id: <number> (notikuma kārtas numurs straumē, sākot no 1) un data: <JSON>, kam seko tukša rinda. Lauki event: un retry: netiek lietoti; notikuma tips ir laukā type (ChatEvent).

Uz jautājumu ar request_id tiek atbildēts neatkarīgi no savienojuma. Atvienošanās atbildi neaptur: tā tiek pabeigta un saglabāta sarunā (līdz 10 minūtēm). Atkārtots tas pats pieprasījums (tas pats request_id un saruna) pievienojas notiekošajai atbildei un ar galveni Last-Event-ID saņem notikumus pēc šī numura, tāpēc straume turpinās ar tiem pašiem notikumu numuriem. Ja straumi nevar turpināt no šī numura, atkārtotais pieprasījums saņem straumi no sākuma: pirmajam notikumam tad ir numurs, kas nav lielāks par Last-Event-ID, un klients sāk atbildi no jauna. Ja atbilde jau ir pabeigta un tās notikumu buferis atbrīvots (pēc 3 minūtēm), saglabātais rezultāts tiek nosūtīts vēlreiz (token un done, numurēti no 1), jautājumu neuzdodot vēlreiz; citādi atbilde tiek ģenerēta no jauna. Lai apturētu šādu atbildi, izsauciet POST /v1/chat/cancel. Bez request_id klienta atvienošanās atceļ atbildi.

Pēc pirmā notikuma, kamēr atbilde tiek veidota, serveris ik pēc 15 sekundēm nosūta komentāru : ping; izlaidiet to. Notikumu secība: notikumi stage (progress), meta, sources, data, pēc tam atbildes teksts notikumos token, pēc tam done. Pirms atbildes teksta sources un data var atkārtoties un var parādīties notikumi tool; teksts var pienākt kā viens token vai pa daļām. Atbilde no kešatmiņas: meta (ar cached), sources, data, token, done. Kļūda pēc straumes sākuma pienāk kā notikums error, un straume aizveras bez done; straumes HTTP statuss vienmēr ir 200. Pēc done var pienākt notikums followups ar ieteiktajiem nākamajiem jautājumiem. Ignorējiet notikumu tipus, kurus neapstrādājat.

Ar stream=false: application/json ar AnswerResponse saturu (kā arī conversation_id).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

text/event-stream

Objekts: ChatEvent

Viens no

application/json

Objekts: AnswerResponse

answerstringobligāts
question_idintegerobligāts
querystring
collectionstringobligāts
sourcesarray of Sourceobligāts
table_queriesarray of TableQueryobligāts
datasetsarray of Datasetobligāts
chartsarray of ChartSpecobligāts
warningsarray of AnswerWarningobligāts
timingsTimingsobligāts
provenancearray of NumberProvenance
emptystring
Atļautās vērtības: 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
Kāpēc šai atbildei izmantoti rīki: request (skaidri pieprasīts); compare, compute, action (pēc jautājuma); needs_calc (nepieciešams aprēķins pa tabulām); summary (kolekcijas vai dokumentu pārskats); mcp (organizācijai ir pievienoti ārēji MCP serveri).
Atļautās vērtības: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityobligāts
followupsarray of Followupobligāts
conversation_idstring
Tikai POST /v1/chat ar sarunu.
answer_idstring
Atbildes objekta ID.

400Pieprasījums nav derīgs: parametra vērtība vai objekta stāvoklis neļauj veikt darbību (`detail` ir ziņojums).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

403Darbība nav atļauta: loma nav pietiekama, nav piekļuves kolekcijai vai kartītei, pieprasījums izpildās režīmā „View as“ vai organizācija ir apturēta vai dzēsta (`detail` ir objekts ar `code: org_suspended | org_deleted`).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

404Objekts neeksistē vai jums nav pieejams. API neapstiprina, ka ierobežotas piekļuves objekts eksistē.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

422Validācijas kļūda: saturs vai parametri neatbilst shēmai (`detail` ir validācijas kļūdu saraksts), vai parametra vērtība ir ārpus pieļaujamā diapazona (`detail` ir ziņojums).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

429Pārāk daudz pieprasījumu (`api.rate_limited`), organizācijas minūtes, dienas vai mēneša kvota ir izlietota (`api.quota_exceeded`; `error.details` satur `quota`, `limit` un `reset_at`), sasniegts organizācijas limits vai atbilžu pakalpojums ir aizņemts (`answers.engine_busy`). Pagaidiet galvenē `Retry-After` norādīto laiku.

Atbildes galvenes

Retry-After
Sekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.
RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

Kļūdu kodi

Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.

Droši atkārtojumi

Ar katru POST un PATCH pieprasījumu nosūtiet galveni Idempotency-Key (piemēram, UUID). Atkārtots pieprasījums ar to pašu atslēgu 24 stundu laikā atgriež saglabāto atbildi, nevis izpilda pieprasījumu vēlreiz.

Pieprasījumu biežuma limiti

Atbildēs ir galvenes RateLimit un RateLimit-Policy, kā arī agrākās X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset. Atbildē 429 ir galvene Retry-After sekundēs: nogaidiet un atkārtojiet pieprasījumu.

← answers · API rokasgrāmata

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"

Izmēģināt

API atslēga

Atslēga glabājas tikai šīs cilnes atmiņā un tiek sūtīta tikai uz https://api.sursa.com.

Pieprasījumi darbojas ar jūsu organizācijas reālajiem datiem.

X-View-As header

Idempotency-Key

Ja lauks ir tukšs, katram pieprasījumam tiek ģenerēta jauna atslēga.

Pieprasījuma saturs (JSON)