Hoppa till innehållet
Sursa Developers

POST/v1/chat

Strömma ett svar från assistenten (SSE)

chat

Med flera API-instanser bakom en lastbalanserare (adressen api.<domain>, 1.62.0) finns ett svar och bufferten med dess händelser i minnet hos den instans som genererar det. Att återuppta strömmen med Last-Event-ID fungerar bara mot den instansen.

Ett upprepat anrop med samma request_id och konversation som når en annan instans när svaret redan är klart får det sparade svaret (token och done, händelser numrerade från 1) utan att frågan ställs igen. Ett upprepat anrop som når en annan instans medan svaret fortfarande genereras stoppar den genereringen och bygger svaret på nytt; inte heller då skapas någon ny fråga. Om du vill återuppta strömmen utan en ny generering behåller du anslutningen till samma instans eller upprepar anropet efter händelsen done.

Autentisering

Skicka en API-nyckel i huvudet Authorization: Authorization: Bearer <nyckel>.

Parametrar i huvuden

  • X-View-Asstring

    Bara för API-nycklar med rollen admin. Gör anropet som dataprofilen <profile>[:viewer|verifier|editor], till exempel employee:viewer. Installationsnyckeln kan inte använda det här huvudet (403).

Cookie-parametrar

  • kb_view_asstring

    Cookie för läget ”View as” (visa som en annan användare) i en session. POST /auth/view-as sätter den och DELETE /auth/view-as tar bort den.

Anropets brödtext

application/json

Objekt: ChatRequest

  • messagesarray of ChatMessageobligatorisk

    items ≥ 1

  • collectionstring

    Standard: "default"

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

    items ≤ 50

  • streamboolean

    Standard: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    Ta inte svaret från svarscachen (knappen ”Get a fresh answer” under ett cachat svar). Det nya svaret ersätter posten i cachen.

    Standard: false

  • languagestring | null

    Svarsspråk: en ISO 639-1-kod (de, en, ru, …) för att svara på det språket. Med auto eller utan fältet identifieras språket utifrån frågan. Gränssnittet skickar uttryckligen språket för ett förslag på ett annat språk (Starter.language).

  • scopeChatScope | null

    Frågans avgränsning: flera samlingar, en källa, taggar och en period. Avgränsningens samlingar ersätter collection. En källa begränsar svaret till källans samling (och dess egna kort). Taggarna läggs till i tags. Perioden begränsar finansiella svar till den perioden. Du kan bara välja det som användaren ser (samlingar: collections.no_access/collections.not_found; källa: sources.not_found). Med conversation_id sparas avgränsningen i konversationen. Utan fältet gäller konversationens avgränsning; null eller en tom avgränsning rensar den.

  • request_idstring

    Frågans idempotensnyckel. Skicka samma nyckel i varje nytt försök av strömmen för en fråga (ett nytt försök efter ett avbrott; här fortsätter Last-Event-ID inte strömmen och loggas bara). Ett nytt försök med nyckeln till ett svar som redan har sparats skapar ingen andra fråga: det sparade resultatet skickas igen som en händelse done (och en token med texten), även om gränsen för frågor eller krediter är uttömd. Om det föregående svaret fortfarande genereras för en klient som har kopplats från, stoppas den genereringen och svaret genereras på nytt.

    length ≤ 64

  • version_ofinteger (int64)

    Skapar en ny version av den här frågans omgång i konversationen (question_id från flödet): en redigerad fråga (ny text i messages), ett omgenererat svar (samma text, oftast med bypass_cache) eller samma fråga med en annan quality (till exempel precise efter ett fast-svar). Det tidigare paret av fråga och svar behålls. Omgångarna efter det stannar i dess gren och döljs i flödet medan den nya versionen är vald (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Historiken som används för svaret är den valda grenen fram till den här omgången. En versions quality ändrar inte konversationens inställningar. Kräver conversation_id; en fråga från en annan konversation returnerar 404 questions.not_found.

  • qualitystring

    Balans mellan snabbhet och noggrannhet i sökningen bakom resultatet: fast är snabbare, precise är noggrannare. Standard: precise.

    Tillåtna värden: fastprecise

Svar

200Med `stream=true`: `text/event-stream`. Varje händelse består av raderna `id: <number>` (händelsens löpnummer i strömmen, från 1) och `data: <JSON>`, följda av en tom rad. Fälten `event:` och `retry:` används inte; händelsetypen finns i fältet `type` (`ChatEvent`).

Med stream=true: text/event-stream. Varje händelse består av raderna id: <number> (händelsens löpnummer i strömmen, från 1) och data: <JSON>, följda av en tom rad. Fälten event: och retry: används inte; händelsetypen finns i fältet type (ChatEvent).

En fråga med request_id besvaras oberoende av anslutningen. En frånkoppling stoppar inte svaret: det slutförs och sparas i konversationen (i upp till 10 minuter). Om samma anrop upprepas (samma request_id och konversation) kopplas det till svaret som pågår, och med huvudet Last-Event-ID får det händelserna efter det numret, så strömmen fortsätter med samma händelsenummer. Om strömmen inte kan fortsätta från det numret får det upprepade anropet strömmen från början: den första händelsen har då ett nummer som inte är större än Last-Event-ID, och klienten börjar om med svaret. Om svaret redan är klart och dess händelsebuffert har frigjorts (efter 3 minuter) skickas det sparade resultatet igen (token och done, numrerade från 1) utan att frågan ställs igen; annars genereras svaret på nytt. Anropa POST /v1/chat/cancel för att stoppa ett sådant svar. Utan request_id avbryter en frånkoppling från klienten svaret.

Efter den första händelsen, medan svaret pågår, skickar servern en kommentar : ping var 15:e sekund; hoppa över den. Ordningen på händelserna: händelser stage (förlopp), meta, sources, data, sedan svarstexten i händelser token och sist done. Före svarstexten kan sources och data upprepas och händelser tool förekomma; texten kan komma som en enda token eller i delar. Ett cachat svar: meta (med cached), sources, data, token, done. Ett fel efter att strömmen har startat kommer som en händelse error, och strömmen stängs utan done; strömmens HTTP-status är alltid 200. Efter done kan en händelse followups med förslag på nästa frågor komma. Ignorera händelsetyper som du inte hanterar.

Med stream=false: application/json med brödtexten AnswerResponse (plus conversation_id).

Svarshuvuden

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

text/event-stream

Objekt: ChatEvent

Ett av

application/json

Objekt: AnswerResponse

  • answerstringobligatorisk
  • question_idintegerobligatorisk
  • querystring
  • collectionstringobligatorisk
  • sourcesarray of Sourceobligatorisk
  • table_queriesarray of TableQueryobligatorisk
  • datasetsarray of Datasetobligatorisk
  • chartsarray of ChartSpecobligatorisk
  • warningsarray of AnswerWarningobligatorisk
  • timingsTimingsobligatorisk
  • provenancearray of NumberProvenance
  • emptystring

    Tillåtna värden: 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

    Varför verktyg användes för det här svaret: request (uttryckligen begärt); compare, compute, action (utifrån frågan); needs_calc (en beräkning över tabeller behövs); summary (en översikt över en samling eller dokument); mcp (organisationen har anslutit externa MCP-servrar).

    Tillåtna värden: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityobligatorisk
  • followupsarray of Followupobligatorisk
  • conversation_idstring

    Bara för POST /v1/chat med en konversation.

  • answer_idstring

    Svarsobjektets id.

400Anropet är ogiltigt: ett parametervärde eller objektets tillstånd tillåter inte åtgärden (`detail` är ett meddelande).

Svarshuvuden

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

401Inga autentiseringsuppgifter skickades (varken en sessionscookie eller en API-nyckel), eller så hittades inte nyckeln.

Svarshuvuden

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

403Åtgärden är inte tillåten: rollen räcker inte, det saknas åtkomst till samlingen eller kortet, anropet körs i läget ”View as” (visa som en annan användare), eller organisationen är avstängd eller borttagen (`detail` är ett objekt med `code: org_suspended | org_deleted`).

Svarshuvuden

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

404Objektet finns inte eller är inte tillgängligt för dig. API:et bekräftar inte att ett begränsat objekt finns.

Svarshuvuden

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

422Valideringsfel: brödtexten eller parametrarna stämmer inte med schemat (`detail` är en lista med valideringsfel), eller så ligger ett parametervärde utanför det tillåtna intervallet (`detail` är ett meddelande).

Svarshuvuden

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

429För många anrop (`api.rate_limited`), organisationens kvot för minuten, dygnet eller månaden är förbrukad (`api.quota_exceeded`; `error.details` innehåller `quota`, `limit` och `reset_at`), organisationens gräns är nådd eller svarstjänsten är upptagen (`answers.engine_busy`). Vänta den tid som anges i huvudet `Retry-After`.

Svarshuvuden

  • Retry-After

    Antal sekunder att vänta innan du skickar anropet igen.

  • RateLimit-Policy

    Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.

  • RateLimit

    Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).

  • X-RateLimit-Remaining

    Återstående anrop inom den striktaste gränsen.

  • X-RateLimit-Reset

    Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

Felkoder

Koder som den här slutpunkten kan returnera i error.code, utöver de allmänna koderna för alla anrop.

Säkra nya försök

Skicka huvudet Idempotency-Key (till exempel ett UUID) med varje POST och PATCH. Ett nytt försök med samma nyckel inom 24 timmar returnerar det sparade svaret i stället för att köra anropet igen.

Hastighetsbegränsningar

Svaren innehåller huvudena RateLimit och RateLimit-Policy samt de tidigare X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset. Ett 429-svar har Retry-After i sekunder: vänta och försök igen.

← answers · API-referens