Salt la conținut
Sursa Developers

POST/v1/chat

Transmite în flux un răspuns al asistentului (SSE)

chat

Cu mai multe copii ale API-ului în spatele unui echilibrator de sarcină (adresa api.<domain>, 1.62.0), un răspuns și memoria tampon a evenimentelor lui se află în memoria copiei care îl generează. Reluarea fluxului cu Last-Event-ID funcționează doar pe acea copie.

O cerere repetată cu același request_id și aceeași conversație, care ajunge la altă copie după ce răspunsul s-a încheiat, primește răspunsul salvat (token și done, evenimente numerotate de la 1) fără ca întrebarea să fie pusă din nou. O cerere repetată care ajunge la altă copie cât timp răspunsul încă se generează oprește acea generare și construiește răspunsul din nou; nici în acest caz nu se creează o a doua întrebare. Pentru a relua fluxul fără o generare nouă, păstrați conexiunea cu aceeași copie sau repetați cererea după evenimentul done.

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de antet

  • X-View-Asstring

    Doar pentru cheile API cu rolul admin. Execută cererea cu profilul de date <profile>[:viewer|verifier|editor], de exemplu employee:viewer. Cheia de instalare nu poate folosi acest antet (403).

Parametri cookie

  • kb_view_asstring

    Cookie-ul modului „View as” (vizualizare ca alt utilizator) pentru o sesiune. POST /auth/view-as îl setează, iar DELETE /auth/view-as îl șterge.

Corpul cererii

application/json

Obiect: ChatRequest

  • messagesarray of ChatMessageobligatoriu

    items ≥ 1

  • collectionstring

    Implicit: "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • streamboolean

    Implicit: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Nu se ia răspunsul din cache-ul răspunsurilor (butonul „Get a fresh answer” sub un răspuns din cache). Răspunsul nou înlocuiește intrarea din cache.

    Implicit: false

  • languagestring | null

    Limba răspunsului: un cod ISO 639-1 (de, en, ru, …) pentru a răspunde în acea limbă. Cu auto sau fără câmp, limba se determină după întrebare. Interfața transmite explicit limba unei sugestii într-o altă limbă (Starter.language).

  • scopeChatScope | null

    Aria întrebării: mai multe colecții, o sursă, etichete și o perioadă. Colecțiile din arie înlocuiesc collection. O sursă restrânge răspunsul la colecția ei (și la propriile ei fișe). Etichetele se adaugă la tags. Perioada limitează răspunsurile financiare la acea perioadă. Se poate selecta doar ce vede utilizatorul (colecții: collections.no_access/collections.not_found; sursă: sources.not_found). Cu conversation_id, aria se salvează în conversație. Fără câmp se aplică aria conversației; null sau o arie goală o șterge.

  • request_idstring

    Cheia de idempotență a întrebării. Trimiteți aceeași cheie la fiecare reîncercare a fluxului pentru o întrebare (o reîncercare după o deconectare; aici Last-Event-ID nu continuă fluxul și este doar înregistrat în jurnal). O reîncercare cu cheia unui răspuns deja salvat nu creează o a doua întrebare: rezultatul salvat se trimite din nou ca un singur eveniment done (și un token cu textul), chiar dacă limita de întrebări sau de credite este epuizată. Dacă răspunsul anterior este încă în curs de generare pentru un client deconectat, acea generare se oprește și răspunsul se generează din nou.

    length ≤ 64

  • version_ofinteger (int64)

    Creează o nouă versiune a schimbului acestei întrebări în conversație (question_id din istoric): o întrebare editată (text nou în messages), un răspuns regenerat (același text, de obicei cu bypass_cache) sau aceeași întrebare cu alt quality (de exemplu, precise după un răspuns fast). Perechea anterioară de întrebare și răspuns se păstrează. Schimburile de după ea rămân în ramura ei și sunt ascunse din istoric cât timp este selectată noua versiune (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Istoricul folosit pentru răspuns este ramura selectată până la acest schimb. Valoarea quality a unei versiuni nu modifică setările conversației. Necesită conversation_id; o întrebare din altă conversație returnează 404 questions.not_found.

  • qualitystring

    Echilibrul dintre viteza și precizia căutării pe care se bazează rezultatul: fast este mai rapid, precise este mai precis. Implicit: precise.

    Valori permise: fastprecise

Răspunsuri

200Cu `stream=true`: `text/event-stream`. Fiecare eveniment constă din liniile `id: <number>` (numărul de ordine al evenimentului în flux, începând de la 1) și `data: <JSON>`, urmate de o linie goală. Câmpurile `event:` și `retry:` nu sunt folosite; tipul evenimentului se află în câmpul `type` (`ChatEvent`).

Cu stream=true: text/event-stream. Fiecare eveniment constă din liniile id: <number> (numărul de ordine al evenimentului în flux, începând de la 1) și data: <JSON>, urmate de o linie goală. Câmpurile event: și retry: nu sunt folosite; tipul evenimentului se află în câmpul type (ChatEvent).

O întrebare cu request_id primește răspuns independent de conexiune. O deconectare nu oprește răspunsul: acesta este finalizat și salvat în conversație (timp de cel mult 10 minute). Repetarea aceleiași cereri (același request_id și aceeași conversație) se atașează la răspunsul în curs, iar cu antetul Last-Event-ID primește evenimentele de după acel număr, astfel încât fluxul continuă cu aceleași numere de evenimente. Dacă fluxul nu poate continua de la acel număr, cererea repetată primește fluxul de la început: primul eveniment are atunci un număr cel mult egal cu Last-Event-ID, iar clientul reia răspunsul de la capăt. Dacă răspunsul s-a încheiat deja și memoria tampon a evenimentelor lui a fost eliberată (după 3 minute), rezultatul salvat este trimis din nou (token și done, numerotate de la 1) fără ca întrebarea să fie pusă din nou; altfel, răspunsul este generat din nou. Pentru a opri un astfel de răspuns, apelați POST /v1/chat/cancel. Fără request_id, deconectarea clientului anulează răspunsul.

După primul eveniment, cât timp răspunsul este în curs, serverul trimite un comentariu : ping la fiecare 15 secunde; ignorați-l. Ordinea evenimentelor: evenimente stage (progres), meta, sources, data, apoi textul răspunsului în evenimente token, apoi done. Înainte de textul răspunsului, sources și data se pot repeta și pot apărea evenimente tool; textul poate sosi ca un singur token sau în părți. Un răspuns din cache: meta (cu cached), sources, data, token, done. O eroare apărută după pornirea fluxului sosește ca eveniment error, iar fluxul se închide fără done; statusul HTTP al fluxului este întotdeauna 200. După done poate sosi un eveniment followups cu întrebări următoare sugerate. Ignorați tipurile de evenimente pe care nu le tratați.

Cu stream=false: application/json cu un corp AnswerResponse (plus conversation_id).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

text/event-stream

Obiect: ChatEvent

Unul dintre

application/json

Obiect: AnswerResponse

  • answerstringobligatoriu
  • question_idintegerobligatoriu
  • querystring
  • collectionstringobligatoriu
  • sourcesarray of Sourceobligatoriu
  • table_queriesarray of TableQueryobligatoriu
  • datasetsarray of Datasetobligatoriu
  • chartsarray of ChartSpecobligatoriu
  • warningsarray of AnswerWarningobligatoriu
  • timingsTimingsobligatoriu
  • provenancearray of NumberProvenance
  • emptystring

    Valori permise: 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

    De ce au fost folosite instrumente pentru acest răspuns: request (cerut explicit); compare, compute, action (pe baza întrebării); needs_calc (este necesar un calcul pe tabele); summary (o prezentare de ansamblu a unei colecții sau a unor documente); mcp (organizația a conectat servere MCP externe).

    Valori permise: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityobligatoriu
  • followupsarray of Followupobligatoriu
  • conversation_idstring

    Doar pentru POST /v1/chat cu o conversație.

  • answer_idstring

    ID-ul obiectului răspunsului.

400Cererea este invalidă: valoarea unui parametru sau starea obiectului nu permite acțiunea (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

404Obiectul nu există sau nu vă este disponibil. API-ul nu confirmă existența unui obiect restricționat.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

422Eroare de validare: corpul sau parametrii nu corespund schemei (`detail` este o listă de erori de validare) ori valoarea unui parametru este în afara intervalului permis (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

  • Retry-After

    Numărul de secunde de așteptat înainte de a reîncerca cererea.

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← answers · Referința API