API publique du canal API

Base : origine du service Core, préfixe /public/v1/api.

La clé identifie le locataire et le canal ; aucun channel_id dans l'URL. POST /execute est la seule écriture publique du canal API. Les lectures de conversations et l'API du widget ont leurs propres contrats.

Authentification

Note :

• Envoyez Authorization: Bearer <clé> sur POST et GET.
• Une clé widget ne peut pas appeler ces routes.
• Le canal doit être actif et relié à un flow.
• Un canal archivé renvoie 410, un canal non actif 409.

La publication des flows et des canaux est différée : la console ne permet pour le moment de créer des canaux API et widget qu'en développement. Ce mode exécute le brouillon ; les canaux de production existants exigent toujours une version publiée pour s'exécuter.

POST /public/v1/api/execute

Content-Type : application/json ou multipart/form-data.

Réponse : 200 application/json par défaut, 200 text/event-stream avec ?stream=true.

Corps JSON (application/json)

curl -X POST 'https://api.example.com/public/v1/api/execute' \
  -H 'Authorization: Bearer nx_live_votre_cle' \
  -H 'Content-Type: application/json' \
  -d '{"payload":{"user_message":"Résumez ma commande"}}'

Corps multipart (multipart/form-data)

Le multipart retourne du JSON par défaut et du SSE avec ?stream=true. Un mauvais nom de champ pour les fichiers est rejeté, pas ignoré. Pour un fichier, précisez le type MIME sur la partie multipart et laissez curl définir l'en-tête Content-Type avec sa boundary :

curl -N 'https://api.example.com/public/v1/api/execute?stream=true' \
  -H 'Authorization: Bearer nx_live_votre_cle' \
  -F 'docs=@cv.pptx;type=application/vnd.openxmlformats-officedocument.presentationml.presentation'

Réponse JSON (200)

{
  "run_id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "session_id": "b1f2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "output": {
    "result": { "text": "Votre commande est en chemin." },
    "error": null,
    "messages": [{ "id": "pub_7f6d8e9a", "role": "assistant", "content": "Votre commande est en chemin." }],
    "metadata": {
      "channel_id": "6f1e2d3c-4b5a-6978-8f9e-0a1b2c3d4e5f",
      "flow_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "flow_name": "Commandes",
      "flow_version": null,
      "livechat_mode": null,
      "environment": "dev",
      "execution_order": ["trigger_from_channel", "agent"],
      "started_at": "2026-08-04T10:00:00Z",
      "completed_at": "2026-08-04T10:00:01Z"
    }
  },
  "usage": { "total_nodes": 2, "duration_ms": 1000 },
  "error": null
}

Variantes : un transfert vers le livechat pendant l'appel renvoie pending (output.result, usage.duration_ms et completed_at éventuellement null). Si la session est déjà en livechat, run_id et usage valent null, output.messages vaut [] et output.metadata contient seulement channel_id et livechat_mode.

Réponse SSE (200 text/event-stream)

Chaque trame contient data: <objet JSON>\n\n ; l'objet porte le champ type (pas de champ SSE event:). La fin est la trame littérale data: [DONE]\n\n.

data: {"type":"data-run","data":{"run_id":"9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f","session_id":"b1f2c3d4-e5f6-7890-abcd-ef1234567890"}}

data: {"type":"text-start","id":"pub_7f6d8e9a"}

data: {"type":"text-delta","id":"pub_7f6d8e9a","delta":"Votre commande est en chemin."}

data: {"type":"text-end","id":"pub_7f6d8e9a"}

data: {"type":"finish","finishReason":"stop"}

data: [DONE]

Poursuivre une session et répondre à un nœud Question

À la reprise d'une Question, les autres champs du payload et les fichiers sont ignorés. Une question de clarification d'un Agent en pause (option Autoriser les questions de clarification activée) suit le même contrat : la réponse reprend la même étape Agent.

Fichiers générés

GET /public/v1/api/execute/{session_id}/artifacts/{artifact_id} : téléchargement d'un fichier produit par le flow. artifact_id figure dans output.result de /execute. La route n'existe pas pour l'API widget.

Réessais sans doublons

En-tête POST Idempotency-Key : 1 à 255 caractères non blancs, une valeur par opération. Un réessai doit conserver le même payload, les mêmes fichiers, la même session et le même format JSON/SSE.

La déduplication de l'API ne garantit pas l'exécution unique des effets dans les outils externes.

Signature HMAC

Voir Signer les requêtes pour le calcul et la rotation du secret.

Erreurs

Format habituel : {"error":{"code":"<code>","message":"<message>"}}, avec X-Request-ID. resume_conflict utilise actuellement detail avec retry_after_ms ; http_error est un code de remplacement générique.

Une erreur d'exécution du flow peut aussi renvoyer HTTP 200 avec status: "error" et output.error.

Limitation de débit

En-têtes de réponse : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset décrivent le compteur le plus restrictif. Le refus est 429 rate_limit_exceeded avec Retry-After en secondes. OPTIONS n'est pas débité. En cas d'indisponibilité de Redis, le quota du canal laisse passer les requêtes.

Mesures : Observe affiche les requêtes authentifiées et les 429 des dernières 24 heures (filtrables par canal), y compris celles sans exécution. Ces mesures sont indisponibles si Redis ne peut pas être lu ; Home renvoie vers Observe lorsqu'il y a des rejets.

Annexe : CORS et identifiants des requêtes