Routes des gateways et de la prédiction

Une gateway est un assistant conversationnel : un graphe de workflow (flow_data) rattaché à un espace de travail, qui peut être publié pour un usage public. Ce chapitre décrit les routes réelles sous /api/v1/gateways, les messages, la prédiction (envoi d'une question), les retours utilisateur, le « warm start » et les sondes de santé.

Convention : les corps de requête et de réponse des routes de ce chapitre sont du JSON en snake_case (sauf mention contraire). Une erreur a la forme {"error": {"code": "...", "message": "..."}}, sauf le dépassement de débit (429, corps vide : voir Swagger). Les listes sont des objets à clé nommée (par exemple {"gateways": [...], "total": N} pour GET /api/v1/gateways) ; le serveur n'ajoute pas d'enveloppe générique {data, meta}.

Gestion des gateways

Toutes ces routes exigent un jeton (Authorization: Bearer <token>) et sont cloisonnées par organisation : un espace de travail hors de votre périmètre est refusé. L'identifiant d'espace de travail (workspace_id) se lit par GET /api/v1/workspaces (réponse {"workspaces": [...], "total": N}, avec l'id de chaque espace). Parcours minimal pour exposer un assistant : POST /api/v1/gateways, puis POST /api/v1/gateways/{id}/publish, puis POST /api/v1/prediction/{id}. <hote-api> est défini dans Swagger.

POST /api/v1/gateways

Corps (structure CreateGatewayRequest) : name et workspace_id sont obligatoires ; flow_data est une chaîne JSON ; gateway_type, chatbot_config et deployed sont facultatifs.

curl -X POST "https://<hote-api>/api/v1/gateways" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Assistant comptabilite","workspace_id":"<uuid-espace>","flow_data":"{\"nodes\":[],\"edges\":[]}","deployed":false}'

Réponse 201 avec la gateway : id, name, type, deployed, is_public, category, workspace_id, created_at, updated_at, approval_required, et public_token / public_expires_at / flow_data / last_transfer quand ils existent (flow_data n'est pas renvoyé dans la liste). Le plafond du plan est appliqué à la création : au-delà du quota de gateways ou de workflows, la réponse est un refus de quota (402, ou 503 si le quota ne peut pas être évalué).

PUT /api/v1/gateways/{id} accepte, tous facultatifs : name, flow_data, deployed, is_public, chatbot_config, api_config, category et approval_required (supervision humaine par gateway).

Publication

curl -X POST "https://<hote-api>/api/v1/gateways/<gateway-id>/publish" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"expires_at":"2027-01-31T23:59:59Z"}'

Le corps JSON est attendu même sans expiration : envoyez {}. expires_at (RFC 3339) est facultatif ; une valeur mal formée est refusée plutôt qu'ignorée (400, code VALIDATION_ERROR). Pour une gateway dont le graphe désigne un patient (lien patient), l'expiration est obligatoire en pratique : sans expires_at elle vaut 30 jours, au-delà de 90 jours ou dans le passé la publication est refusée (constantes fixées dans le code). La réponse est la gateway à jour, avec son public_token.

Transfert, budget

POST .../transfer prend to_workspace_id (obligatoire), reason et transmission_note. POST /api/v1/gateways/transfer-batch prend from_workspace_id, to_workspace_id et, facultativement, gateway_ids, reason, transmission_note. PATCH .../budget prend {"monthly_limit": <entier>} ; 0 signifie illimité.

Historique des conversations

GET .../chat-messages prend chatId (la conversation) et order (ASC par défaut, ou DESC). GET .../chat-sessions accepte chatType mais ne filtre pas dessus : la plateforme n'enregistre pas le canal d'une conversation.

curl "https://<hote-api>/api/v1/gateways/<gateway-id>/chat-messages?chatId=conv-123&order=ASC" \
  -H "Authorization: Bearer <token>"

GET /api/v1/gateway-messages prend limit et offset et renvoie {"gateway_messages": [...], "total": N, "offset": ..., "limit": ...}. POST /api/v1/gateway-messages prend role, mcp_gateway_id, content, chat_type et chat_id (et session_id facultatif). Un message d'une gateway d'une autre organisation répond 403.

Prédiction : poser une question

POST /api/v1/prediction/{id}

{id} est l'identifiant de la gateway. Cette route sert le widget intégrable ; elle ne demande pas de jeton, mais la gateway doit être publiée. Corps : question (ou message), sessionId facultatif, streaming facultatif (accepté, mais la réponse est toujours consolidée en un seul bloc).

curl -X POST "https://<hote-api>/api/v1/prediction/<gateway-id>" \
  -H "Content-Type: application/json" \
  -d '{"question":"Quels sont les clients avec un chiffre d affaires superieur a 100k ?","sessionId":"conv-123"}'

Réponse (forme de la branche d'exécution d'outil) :

{
  "gateway_id": "<uuid>",
  "chat_id": "conv-123",
  "text": "Voici les clients...",
  "response": "Voici les clients...",
  "generated_by": { "...": "marquage IA" },
  "agent": {
    "tool": "<outil utilisé>",
    "module": "<module>",
    "resolution_path": "<chemin de résolution>",
    "confidence": 0.9
  }
}

Cas particuliers : 400 MISSING_QUESTION si ni question ni message ; 403 SECURITY_BLOCKED si le garde d'injection de prompt bloque l'entrée ; une demande de conseil clinique reçoit un refus rédigé avec refusal_reason. POST /api/v1/prediction (sans identifiant) répond 412 ID_REQUIRED. Le quota par défaut est de 20 requêtes par minute et par adresse IP sur le préfixe /api/v1/prediction (variable FORGE_RATE_LIMIT_PREDICTION_PER_MIN). Le limiteur compare le début du chemin : /api/v1/predictions et /api/v1/predictions/stream tombent dans le même seau.

POST /api/v1/predictions

Complétion directe, jeton obligatoire. Corps : prompt (obligatoire), system, model, max_tokens, temperature, session_id. Réponse : {"text", "model", "tokens", "latency_ms", "generated_by"}.

Retours utilisateur

Corps de création : message_id (uuid), gateway_id (uuid), chat_id, rating (thumbs_up, thumbs_down ou null) et content. Un autre rating répond 422 VALIDATION_FAILED.

Warm start

Capacité en sommeil. Cette route répond aujourd'hui toujours {"warmStart": false, "predictiveQuestion": null, ...} avec le drapeau "shim_pending_v2_1": true. La détection d'inactivité et la question prédictive ne sont pas livrées ; elles sont portées par la tâche T-V1M2-ENGINES-04 de la spec 23. Le userId doit être le vôtre (un rôle admin ou owner peut interroger un autre utilisateur) ; sinon 403, et 400 si userId est absent.

Santé

Ces quatre routes sont publiques (voir Supervision). readyz ne sonde que PostgreSQL et Valkey ; l'état d'Ollama et de Qdrant se lit dans /api/v1/health/status.

curl "https://<hote-api>/api/v1/readyz"

Voir aussi

• Chat : la page qui consomme ces routes, onglets, historique et messages proactifs
• Routes des ressources : document stores, identifiants et variables rattachés aux espaces de travail
• Documentation Swagger : obtention du jeton, format des erreurs et limites de débit
• Routes MCP : transport MCP par session, pour appeler directement les outils
• Analytique : mesures de conversations et de messages dans l'application