POST/v1/chat

Recevoir une réponse de l’assistant en flux (SSE)

chat

Avec plusieurs copies de l’API derrière un répartiteur de charge (l’adresse api.<domain>, 1.62.0), une réponse et le tampon de ses événements résident dans la mémoire de la copie qui la génère. La reprise du flux avec Last-Event-ID ne fonctionne que sur cette copie.

Une requête répétée avec le même request_id et la même conversation qui atteint une autre copie après la fin de la réponse reçoit la réponse enregistrée (token et done, événements numérotés à partir de 1) sans que la question soit posée de nouveau. Une requête répétée qui atteint une autre copie pendant la génération de la réponse arrête cette génération et construit la réponse à nouveau ; aucune seconde question n’est créée non plus. Pour reprendre le flux sans nouvelle génération, conservez la connexion à la même copie ou répétez la requête après l’événement done.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres d’en-tête

X-View-Asstring
Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

kb_view_asstring
Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Corps de la requête

application/json

Objet : ChatRequest

messagesarray of ChatMessageobligatoire
items ≥ 1
collectionstring
Par défaut : "default"
tagsarray of string | null
exportstring | null
card_idsarray of string | null
items ≤ 50
streamboolean
Par défaut : false
conversation_idstring | null
length ≤ 64
originstring | null
toolsboolean | null
bypass_cacheboolean
Ne pas prendre la réponse dans le cache des réponses (le bouton « Get a fresh answer » sous une réponse en cache). La nouvelle réponse remplace l’entrée en cache.
Par défaut : false
languagestring | null
Langue de la réponse : un code ISO 639-1 (de, en, ru, …) pour répondre dans cette langue. Avec auto ou sans le champ, la langue est déduite de la question. L’interface transmet explicitement la langue d’une suggestion rédigée dans une autre langue (Starter.language).
scopeChatScope | null
Périmètre de la question : plusieurs collections, une source, des étiquettes et une période. Les collections du périmètre remplacent collection. Une source restreint la réponse à sa collection (et à ses propres fiches). Les étiquettes s’ajoutent à tags. La période limite les réponses financières à cette période. Vous ne pouvez sélectionner que ce que l’utilisateur voit (collections : collections.no_access/collections.not_found ; source : sources.not_found). Avec conversation_id, le périmètre est enregistré dans la conversation. Sans le champ, le périmètre de la conversation s’applique ; null ou un périmètre vide l’efface.
request_idstring
Clé d’idempotence de la question. Envoyez la même clé à chaque nouvelle tentative du flux pour une même question (nouvelle tentative après une déconnexion ; ici, Last-Event-ID ne reprend pas le flux et est seulement journalisé). Une nouvelle tentative avec la clé d’une réponse déjà enregistrée ne crée pas de seconde question : le résultat enregistré est renvoyé sous la forme d’un seul événement done (et d’un token avec le texte), même si la limite de questions ou de crédits est épuisée. Si la réponse précédente est encore en cours de génération pour un client déconnecté, cette génération s’arrête et la réponse est générée à nouveau.
length ≤ 64
version_ofinteger (int64)
Crée une nouvelle version de l’échange de cette question dans la conversation (question_id issu du fil) : une question modifiée (nouveau texte dans messages), une réponse régénérée (le même texte, généralement avec bypass_cache) ou la même question avec une autre quality (par exemple precise après une réponse fast). La paire question-réponse précédente est conservée. Les échanges qui la suivent restent dans sa branche et sont masqués du fil tant que la nouvelle version est sélectionnée (FeedItem.versions, POST /v1/conversations/{conv_id}/versions). L’historique utilisé pour la réponse est la branche sélectionnée jusqu’à cet échange. La quality d’une version ne modifie pas les paramètres de la conversation. Nécessite conversation_id ; une question d’une autre conversation renvoie 404 questions.not_found.
qualitystring
Équilibre entre la rapidité et la précision de la recherche qui produit le résultat : fast est plus rapide, precise plus précis. Par défaut : precise.
Valeurs autorisées: fastprecise

Réponses

200Avec `stream=true` : `text/event-stream`. Chaque événement se compose des lignes `id: <number>` (le numéro de séquence de l’événement dans le flux, à partir de 1) et `data: <JSON>`, suivies d’une ligne vide. Les champs `event:` et `retry:` ne sont pas utilisés ; le type d’événement figure dans le champ `type` (`ChatEvent`).

Avec stream=true : text/event-stream. Chaque événement se compose des lignes id: <number> (le numéro de séquence de l’événement dans le flux, à partir de 1) et data: <JSON>, suivies d’une ligne vide. Les champs event: et retry: ne sont pas utilisés ; le type d’événement figure dans le champ type (ChatEvent).

Une question avec request_id reçoit sa réponse indépendamment de la connexion. Une déconnexion n’arrête pas la réponse : elle est terminée et enregistrée dans la conversation (pendant 10 minutes au plus). Répéter la même requête (même request_id et même conversation) rattache le client à la réponse en cours, et avec l’en-tête Last-Event-ID, la requête reçoit les événements qui suivent ce numéro : le flux continue donc avec les mêmes numéros d’événements. Si le flux ne peut pas reprendre à partir de ce numéro, la requête répétée reçoit le flux depuis le début : le premier événement porte alors un numéro inférieur ou égal à Last-Event-ID, et le client reprend la réponse depuis le début. Si la réponse est déjà terminée et que le tampon de ses événements a été libéré (au bout de 3 minutes), le résultat enregistré est renvoyé (token et done, numérotés à partir de 1) sans que la question soit posée de nouveau ; sinon, la réponse est générée à nouveau. Pour arrêter une telle réponse, appelez POST /v1/chat/cancel. Sans request_id, une déconnexion du client annule la réponse.

Après le premier événement, tant que la réponse est en cours, le serveur envoie un commentaire : ping toutes les 15 secondes ; ignorez-le. Ordre des événements : événements stage (progression), meta, sources, data, puis le texte de la réponse dans des événements token, puis done. Avant le texte de la réponse, sources et data peuvent se répéter et des événements tool peuvent apparaître ; le texte peut arriver en un seul token ou en plusieurs parties. Une réponse en cache : meta (avec cached), sources, data, token, done. Une erreur survenue après le début du flux arrive sous forme d’événement error, et le flux se ferme sans done ; le statut HTTP du flux est toujours 200. Après done, un événement followups avec des suggestions de questions suivantes peut arriver. Ignorez les types d’événements que vous ne traitez pas.

Avec stream=false : application/json avec un corps AnswerResponse (plus conversation_id).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

text/event-stream

Objet : ChatEvent

L’un des suivants

application/json

Objet : AnswerResponse

answerstringobligatoire
question_idintegerobligatoire
querystring
collectionstringobligatoire
sourcesarray of Sourceobligatoire
table_queriesarray of TableQueryobligatoire
datasetsarray of Datasetobligatoire
chartsarray of ChartSpecobligatoire
warningsarray of AnswerWarningobligatoire
timingsTimingsobligatoire
provenancearray of NumberProvenance
emptystring
Valeurs autorisées: 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
Raison de l’utilisation d’outils pour cette réponse : request (demandé explicitement) ; compare, compute, action (selon la question) ; needs_calc (un calcul sur des tableaux est nécessaire) ; summary (une vue d’ensemble d’une collection ou de documents) ; mcp (l’organisation a connecté des serveurs MCP externes).
Valeurs autorisées: requestcomparecomputeactionneeds_calcsummarymcpnull
tool_callsarray of ToolCallInfo
calculationsarray of Calculation
pending_actionsarray of PendingAction
entitiesarray of AnswerEntityobligatoire
followupsarray of Followupobligatoire
conversation_idstring
Uniquement pour POST /v1/chat avec une conversation.
answer_idstring
ID de l’objet réponse.

400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

Retry-After
Nombre de secondes à attendre avant de réessayer la requête.
RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← answers · Référence de l’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"

Essayer

Clé API

La clé reste dans la mémoire de cet onglet et n’est envoyée qu’à https://api.sursa.com.

Les requêtes agissent sur les données réelles de votre organisation.

X-View-As header

Idempotency-Key

Si ce champ est vide, une nouvelle clé est générée pour chaque requête.

Corps de la requête (JSON)