Zum Inhalt springen
Sursa Developers

POST/v1/chat

Antwort des Assistenten streamen (SSE)

chat

Bei mehreren Instanzen der API hinter einem Load Balancer (die Adresse api.<domain>, 1.62.0) liegen eine Antwort und der Puffer ihrer Ereignisse im Speicher der Instanz, die sie erzeugt. Das Fortsetzen des Streams mit Last-Event-ID funktioniert nur auf dieser Instanz.

Eine wiederholte Anfrage mit derselben request_id und Unterhaltung, die nach Abschluss der Antwort eine andere Instanz erreicht, erhält die gespeicherte Antwort (token und done, Ereignisse ab 1 nummeriert), ohne die Frage erneut zu stellen. Eine wiederholte Anfrage, die eine andere Instanz erreicht, während die Antwort noch erzeugt wird, stoppt diese Erzeugung und erstellt die Antwort neu; auch dabei entsteht keine zweite Frage. Um den Stream ohne neue Erzeugung fortzusetzen, halten Sie die Verbindung zur selben Instanz oder wiederholen Sie die Anfrage nach dem Ereignis done.

Authentifizierung

Senden Sie einen API-Schlüssel im Header Authorization: Authorization: Bearer <Schlüssel>.

Header-Parameter

  • X-View-Asstring

    Nur für API-Schlüssel mit der Rolle admin. Führt die Anfrage mit dem Datenprofil <profile>[:viewer|verifier|editor] aus, zum Beispiel employee:viewer. Der Installationsschlüssel kann diesen Header nicht verwenden (403).

Cookie-Parameter

  • kb_view_asstring

    Cookie des Modus „Ansicht als“ für eine Sitzung. POST /auth/view-as setzt es, DELETE /auth/view-as entfernt es.

Anfragetext

application/json

Objekt: ChatRequest

  • messagesarray of ChatMessageerforderlich

    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

    Die Antwort nicht aus dem Antwort-Cache nehmen (die Schaltfläche „Neue Antwort abrufen“ unter einer zwischengespeicherten Antwort). Die neue Antwort ersetzt den Eintrag im Cache.

    Standard: false

  • languagestring | null

    Sprache der Antwort: ein Code nach ISO 639-1 (de, en, ru, …), um in dieser Sprache zu antworten. Mit auto oder ohne das Feld wird die Sprache aus der Frage erkannt. Die Oberfläche übergibt die Sprache eines Vorschlags in einer anderen Sprache explizit (Starter.language).

  • scopeChatScope | null

    Bereich der Frage: mehrere Sammlungen, eine Quelle, Tags und ein Zeitraum. Die Sammlungen des Bereichs ersetzen collection. Eine Quelle schränkt die Antwort auf ihre Sammlung (und ihre eigenen Karten) ein. Tags werden zu tags hinzugefügt. Der Zeitraum beschränkt Finanzantworten auf diesen Zeitraum. Sie können nur auswählen, was der Benutzer sehen kann (Sammlungen: collections.no_access/collections.not_found; Quelle: sources.not_found). Mit conversation_id wird der Bereich in der Unterhaltung gespeichert. Ohne das Feld gilt der Bereich der Unterhaltung; null oder ein leerer Bereich setzt ihn zurück.

  • request_idstring

    Idempotenzschlüssel der Frage. Senden Sie denselben Schlüssel bei jeder Wiederholung des Streams für eine Frage (eine Wiederholung nach einem Verbindungsabbruch; hier setzt Last-Event-ID den Stream nicht fort und wird nur protokolliert). Eine Wiederholung mit dem Schlüssel einer bereits gespeicherten Antwort erstellt keine zweite Frage: Das gespeicherte Ergebnis wird erneut als ein Ereignis done gesendet (und ein token mit dem Text), selbst wenn das Limit für Fragen oder Credits erschöpft ist. Wird die vorherige Antwort für einen getrennten Client noch erzeugt, wird diese Erzeugung gestoppt und die Antwort neu erzeugt.

    length ≤ 64

  • version_ofinteger (int64)

    Erstellt eine neue Version der Gesprächsrunde dieser Frage in der Unterhaltung (question_id aus dem Verlauf): eine bearbeitete Frage (neuer Text in messages), eine neu erzeugte Antwort (derselbe Text, meist mit bypass_cache) oder dieselbe Frage mit einer anderen quality (zum Beispiel precise nach einer Antwort mit fast). Das vorherige Paar aus Frage und Antwort bleibt erhalten. Die nachfolgenden Gesprächsrunden bleiben in dessen Zweig und werden im Verlauf ausgeblendet, solange die neue Version ausgewählt ist (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). Als Verlauf für die Antwort dient der ausgewählte Zweig bis zu dieser Gesprächsrunde. Die quality einer Version ändert die Einstellungen der Unterhaltung nicht. Erfordert conversation_id; eine Frage aus einer anderen Unterhaltung ergibt 404 questions.not_found.

  • qualitystring

    Abwägung zwischen Geschwindigkeit und Genauigkeit der Suche hinter dem Ergebnis: fast ist schneller, precise genauer. Standard: precise.

    Zulässige Werte: fastprecise

Antworten

200Mit `stream=true`: `text/event-stream`. Jedes Ereignis besteht aus den Zeilen `id: <number>` (die laufende Nummer des Ereignisses im Stream, beginnend bei 1) und `data: <JSON>`, gefolgt von einer Leerzeile. Die Felder `event:` und `retry:` werden nicht verwendet; der Ereignistyp steht im Feld `type` (`ChatEvent`).

Mit stream=true: text/event-stream. Jedes Ereignis besteht aus den Zeilen id: <number> (die laufende Nummer des Ereignisses im Stream, beginnend bei 1) und data: <JSON>, gefolgt von einer Leerzeile. Die Felder event: und retry: werden nicht verwendet; der Ereignistyp steht im Feld type (ChatEvent).

Eine Frage mit request_id wird unabhängig von der Verbindung beantwortet. Ein Verbindungsabbruch stoppt die Antwort nicht: Die Antwort wird dennoch fertiggestellt und in der Unterhaltung gespeichert (bis zu 10 Minuten). Eine Wiederholung derselben Anfrage (dieselbe request_id und Unterhaltung) schließt sich der laufenden Antwort an und erhält mit dem Header Last-Event-ID die Ereignisse nach dieser Nummer, sodass der Stream mit denselben Ereignisnummern weiterläuft. Kann der Stream nicht ab dieser Nummer fortgesetzt werden, erhält die wiederholte Anfrage den Stream von Anfang an: Das erste Ereignis hat dann eine Nummer, die nicht größer als Last-Event-ID ist, und der Client beginnt die Antwort von vorn. Ist die Antwort bereits abgeschlossen und ihr Ereignispuffer freigegeben (nach 3 Minuten), wird das gespeicherte Ergebnis erneut gesendet (token und done, ab 1 nummeriert), ohne die Frage erneut zu stellen; andernfalls wird die Antwort neu erzeugt. Um eine solche Antwort zu stoppen, rufen Sie POST /v1/chat/cancel auf. Ohne request_id bricht ein Verbindungsabbruch des Clients die Antwort ab.

Nach dem ersten Ereignis sendet der Server, solange die Antwort läuft, alle 15 Sekunden einen Kommentar : ping; überspringen Sie ihn. Reihenfolge der Ereignisse: Ereignisse stage (Fortschritt), meta, sources, data, dann der Text der Antwort in Ereignissen token, dann done. Vor dem Text der Antwort können sich sources und data wiederholen und Ereignisse tool auftreten; der Text kann als ein token oder in Teilen ankommen. Eine zwischengespeicherte Antwort: meta (mit cached), sources, data, token, done. Ein Fehler nach Beginn des Streams kommt als Ereignis error an, und der Stream wird ohne done geschlossen; der HTTP-Status des Streams ist immer 200. Nach done kann ein Ereignis followups mit vorgeschlagenen Folgefragen ankommen. Ignorieren Sie Ereignistypen, die Sie nicht verarbeiten.

Mit stream=false: application/json mit einem Body AnswerResponse (dazu conversation_id).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

text/event-stream

Objekt: ChatEvent

Eines von

application/json

Objekt: AnswerResponse

  • answerstringerforderlich
  • question_idintegererforderlich
  • querystring
  • collectionstringerforderlich
  • sourcesarray of Sourceerforderlich
  • table_queriesarray of TableQueryerforderlich
  • datasetsarray of Dataseterforderlich
  • chartsarray of ChartSpecerforderlich
  • warningsarray of AnswerWarningerforderlich
  • timingsTimingserforderlich
  • provenancearray of NumberProvenance
  • emptystring

    Zulässige Werte: 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

    Warum für diese Antwort Werkzeuge verwendet wurden: request (ausdrücklich angefordert); compare, compute, action (aufgrund der Frage); needs_calc (eine Berechnung über Tabellen ist nötig); summary (eine Übersicht über eine Sammlung oder Dokumente); mcp (die Organisation hat externe MCP-Server verbunden).

    Zulässige Werte: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityerforderlich
  • followupsarray of Followuperforderlich
  • conversation_idstring

    Nur für POST /v1/chat mit einer Unterhaltung.

  • answer_idstring

    ID des Antwortobjekts.

400Die Anfrage ist ungültig: Ein Parameterwert oder der Zustand des Objekts lässt die Aktion nicht zu (`detail` ist eine Meldung).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

401Es wurden keine Anmeldedaten gesendet (weder ein Sitzungscookie noch ein API-Schlüssel), oder der Schlüssel wurde nicht gefunden.

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

403Die Aktion ist nicht erlaubt: Die Rolle reicht nicht aus, es besteht kein Zugriff auf die Sammlung oder Karte, die Anfrage läuft im Modus „Ansicht als“, oder die Organisation ist gesperrt oder gelöscht (`detail` ist ein Objekt mit `code: org_suspended | org_deleted`).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

404Das Objekt existiert nicht oder ist für Sie nicht verfügbar. Die API bestätigt nicht, dass ein eingeschränktes Objekt existiert.

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

422Validierungsfehler: Der Body oder die Parameter entsprechen nicht dem Schema (`detail` ist eine Liste von Validierungsfehlern), oder ein Parameterwert liegt außerhalb des zulässigen Bereichs (`detail` ist eine Meldung).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

429Zu viele Anfragen (`api.rate_limited`), das Kontingent der Organisation für die Minute, den Tag oder den Monat ist aufgebraucht (`api.quota_exceeded`; `error.details` enthält `quota`, `limit` und `reset_at`), das Limit der Organisation ist erreicht, oder der Antwortdienst ist ausgelastet (`answers.engine_busy`). Warten Sie die im Header `Retry-After` angegebene Zeit ab.

Antwort-Header

  • Retry-After

    Anzahl der Sekunden, die Sie warten sollten, bevor Sie die Anfrage wiederholen.

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

Fehlercodes

Codes, die dieser Endpunkt in error.code zurückgeben kann, zusätzlich zu den allgemeinen Codes jeder Anfrage.

Sichere Wiederholungen

Senden Sie bei jedem POST und PATCH einen Header Idempotency-Key (zum Beispiel eine UUID). Eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden gibt die gespeicherte Antwort zurück, statt die Anfrage erneut auszuführen.

Ratenlimits

Antworten enthalten die Header RateLimit und RateLimit-Policy sowie die älteren X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Antwort 429 enthält Retry-After in Sekunden: Warten Sie und versuchen Sie es dann erneut.

← answers · API-Referenz