POST/v1/chat

Trasmettere in streaming una risposta dell’assistente (SSE)

chat

Con più copie dell’API dietro un bilanciatore di carico (l’indirizzo api.<domain>, 1.62.0), una risposta e il buffer dei suoi eventi si trovano nella memoria della copia che la genera. La ripresa dello stream con Last-Event-ID funziona solo su quella copia.

Una richiesta ripetuta con lo stesso request_id e la stessa conversazione che raggiunge un’altra copia dopo che la risposta è terminata riceve la risposta salvata (token e done, eventi numerati da 1) senza porre di nuovo la domanda. Una richiesta ripetuta che raggiunge un’altra copia mentre la risposta è ancora in fase di generazione interrompe quella generazione e costruisce la risposta da capo; anche in questo caso non viene creata una seconda domanda. Per riprendere lo stream senza una nuova generazione, mantieni la connessione con la stessa copia o ripeti la richiesta dopo l’evento done.

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di intestazione

X-View-Asstring
Solo per le chiavi API con il ruolo admin. Esegue la richiesta come il profilo dati <profile>[:viewer|verifier|editor], ad esempio employee:viewer. La chiave di installazione non può usare questa intestazione (403).

Parametri cookie

kb_view_asstring
Cookie della modalità “View as” per una sessione. POST /auth/view-as lo imposta e DELETE /auth/view-as lo cancella.

Corpo della richiesta

application/json

Oggetto: ChatRequest

messagesarray of ChatMessageobbligatorio
items ≥ 1
collectionstring
Predefinito: "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Predefinito: false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Non prendere la risposta dalla cache delle risposte (il pulsante “Get a fresh answer”, ottenere una risposta nuova, sotto una risposta dalla cache). La nuova risposta sostituisce la voce nella cache.
Predefinito: false
languagestring | null
Lingua della risposta: un codice ISO 639-1 (de, en, ru, …) per rispondere in quella lingua. Con auto o senza il campo, la lingua viene rilevata dalla domanda. L’interfaccia passa esplicitamente la lingua di un suggerimento in un’altra lingua (Starter.language).
scopeChatScope | null
Perimetro della domanda: più raccolte, una fonte, tag e un periodo. Le raccolte del perimetro sostituiscono collection. Una fonte restringe la risposta alla sua raccolta (e alle sue schede). I tag si aggiungono a tags. Il periodo limita le risposte finanziarie a quel periodo. Puoi selezionare solo ciò che l’utente può vedere (raccolte: collections.no_access/collections.not_found; fonte: sources.not_found). Con conversation_id, il perimetro viene salvato nella conversazione. Senza il campo si applica il perimetro della conversazione; null o un perimetro vuoto lo azzera.
request_idstring
Chiave di idempotenza della domanda. Invia la stessa chiave in ogni nuovo tentativo dello stream per una stessa domanda (un nuovo tentativo dopo una disconnessione; qui Last-Event-ID non riprende lo stream e viene solo registrato). Un nuovo tentativo con la chiave di una risposta già salvata non crea una seconda domanda: il risultato salvato viene inviato di nuovo come un unico evento done (e un token con il testo), anche se il limite di domande o di crediti è esaurito. Se la risposta precedente è ancora in fase di generazione per un client disconnesso, quella generazione si interrompe e la risposta viene generata di nuovo.
length ≤ 64
version_ofinteger (int64)
Crea una nuova versione del turno di questa domanda nella conversazione (question_id dal feed): una domanda modificata (nuovo testo in messages), una risposta rigenerata (lo stesso testo, di solito con bypass_cache) o la stessa domanda con un altro valore di quality (per esempio precise dopo una risposta fast). La coppia precedente di domanda e risposta viene conservata. I turni successivi restano nel suo ramo e sono nascosti dal feed mentre è selezionata la nuova versione (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). La cronologia usata per la risposta è il ramo selezionato fino a questo turno. Il valore quality di una versione non cambia le impostazioni della conversazione. Richiede conversation_id; una domanda di un’altra conversazione restituisce 404 questions.not_found.
qualitystring
Equilibrio tra velocità e accuratezza della ricerca alla base del risultato: fast è più rapida, precise è più accurata. Predefinito: precise.
Valori ammessi: fastprecise

Risposte

200Con `stream=true`: `text/event-stream`. Ogni evento è composto dalle righe `id: <number>` (il numero progressivo dell’evento nello stream, a partire da 1) e `data: <JSON>`, seguite da una riga vuota. I campi `event:` e `retry:` non vengono usati; il tipo di evento è nel campo `type` (`ChatEvent`).

Con stream=true: text/event-stream. Ogni evento è composto dalle righe id: <number> (il numero progressivo dell’evento nello stream, a partire da 1) e data: <JSON>, seguite da una riga vuota. I campi event: e retry: non vengono usati; il tipo di evento è nel campo type (ChatEvent).

A una domanda con request_id viene data risposta indipendentemente dalla connessione. Una disconnessione non interrompe la risposta: viene completata e salvata nella conversazione (per un massimo di 10 minuti). Ripetendo la stessa richiesta (lo stesso request_id e la stessa conversazione) ci si collega alla risposta in corso e, con l’intestazione Last-Event-ID, si ricevono gli eventi successivi a quel numero, quindi lo stream continua con la stessa numerazione degli eventi. Se lo stream non può continuare da quel numero, la richiesta ripetuta riceve lo stream dall’inizio: il primo evento ha allora un numero non superiore a Last-Event-ID e il client ricomincia la risposta. Se la risposta è già terminata e il buffer dei suoi eventi è stato rilasciato (dopo 3 minuti), il risultato salvato viene inviato di nuovo (token e done, numerati da 1) senza porre di nuovo la domanda; altrimenti la risposta viene generata da capo. Per interrompere una risposta di questo tipo, chiama POST /v1/chat/cancel. Senza request_id, la disconnessione del client annulla la risposta.

Dopo il primo evento, mentre la risposta è in corso, il server invia un commento : ping ogni 15 secondi; ignoralo. Ordine degli eventi: eventi stage (avanzamento), meta, sources, data, poi il testo della risposta in eventi token, poi done. Prima del testo della risposta, sources e data possono ripetersi e possono comparire eventi tool; il testo può arrivare come un unico token o in parti. Una risposta dalla cache: meta (con cached), sources, data, token, done. Un errore dopo l’inizio dello stream arriva come evento error e lo stream si chiude senza done; lo stato HTTP dello stream è sempre 200. Dopo done può arrivare un evento followups con le domande successive suggerite. Ignora i tipi di evento che non gestisci.

Con stream=false: application/json con un corpo AnswerResponse (più conversation_id).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

text/event-stream

Oggetto: ChatEvent

Uno tra

application/json

Oggetto: AnswerResponse

answerstringobbligatorio
question_idintegerobbligatorio
querystring
collectionstringobbligatorio
sourcesarray of Sourceobbligatorio
table_queriesarray of TableQueryobbligatorio
datasetsarray of Datasetobbligatorio
chartsarray of ChartSpecobbligatorio
warningsarray of AnswerWarningobbligatorio
timingsTimingsobbligatorio
provenancearray of NumberProvenance
emptystring
Valori ammessi: 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
Perché sono stati usati strumenti per questa risposta: request (richiesti esplicitamente); compare, compute, action (in base alla domanda); needs_calc (serve un calcolo sulle tabelle); summary (una panoramica di una raccolta o di documenti); mcp (l’organizzazione ha collegato server MCP esterni).
Valori ammessi: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityobbligatorio
followupsarray of Followupobbligatorio
conversation_idstring
Solo per POST /v1/chat con una conversazione.
answer_idstring
ID dell’oggetto della risposta.

400La richiesta non è valida: il valore di un parametro o lo stato dell’oggetto non consente l’azione (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

404L’oggetto non esiste o non è disponibile per te. L’API non conferma l’esistenza di un oggetto con accesso limitato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

Retry-After
Numero di secondi da attendere prima di ripetere la richiesta.
RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Nuovi tentativi sicuri

Invia un’intestazione Idempotency-Key (per esempio un UUID) con ogni POST e PATCH. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la risposta salvata invece di eseguire di nuovo la richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← answers · Riferimento API

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"

Prova

Chiave API

La chiave resta nella memoria di questa scheda del browser e viene inviata solo a https://api.sursa.com.

Le richieste vengono eseguite sui dati reali della tua organizzazione.

X-View-As header

Idempotency-Key

Se il campo è vuoto, per ogni richiesta viene generata una nuova chiave.

Corpo della richiesta (JSON)