Canal HTTP API

Intégrez des applications externes avec Cradle via une API REST locale — sync, async, webhook et authentification scopée.

Le canal HTTP API expose Cradle comme un serveur local pour les applications mobiles, les frontends web, les outils CLI, les cron jobs et les plateformes d'automatisation. Il utilise le même flux triage → RAG → agent → opérateur que Telegram et le widget, donc chaque fonctionnalité se comporte identiquement sur tous les canaux.

Port par défaut : 31416. Le widget utilise 31415 par défaut.

Authentification

Tous les endpoints sous /api/v1/* sauf /api/v1/health nécessitent une clé :

Authorization: Bearer <api-key>

X-Api-Key: <api-key>

Les clés sont scopées. Voir Authentification et scopes pour la grammaire des scopes et les règles de changement de projet.

Scopes par endpoint

Endpoint	Méthode	Scope
`/api/v1/health`	GET	(aucun)
`/api/v1/messages`	POST	`messages:write`
`/api/v1/messages/:chatId`	GET	`messages:read`
`/api/v1/admin/agents`	GET / POST	`agents:read` / `agents:write`
`/api/v1/admin/agents/:id/execute`	POST	`agents:execute`
`/api/v1/admin/kb`	GET	`kb:read`
`/api/v1/admin/models`	GET	`models:read`
`/api/v1/admin/models/:catalogId/pull`	GET	`models:write`
`/api/v1/admin/tickets`	GET	`tickets:read`
`/api/v1/admin/keys`	GET / POST	`admin:*`
`/api/v1/projects`	*	`admin:*`

En-tête de projet

Les clés admin peuvent changer de projet par requête :

curl -H "x-api-key: ck_live_…" \
     -H "x-cradle-project: support" \
     http://127.0.0.1:31416/api/v1/admin/agents

Les clés scopées doivent utiliser le projet auquel elles sont liées, sinon le serveur renvoie 403.

POST /api/v1/messages

Envoie un message dans Cradle.

{
  "text": "What is the warranty policy?",
  "chatId": "client-42",
  "userId": "user-123",
  "meta": { "anything": "you-want" },
  "mode": "sync",
  "webhookUrl": "https://your-app.example.com/cradle-webhook",
  "timeoutMs": 60000
}

Champ	Type	Requis	Description
`text`	string	oui	Texte du message, de 1 à 50 000 caractères
`chatId`	string	non	ID de conversation ; UUID généré si omis. Réutilisez pour le threading.
`userId`	string	non	ID utilisateur externe, stocké dans meta.
`meta`	object	non	Données arbitraires sauvegardées dans `tickets.channel_meta`.
`mode`	enum	non	`sync` (défaut), `async`, `webhook`
`webhookUrl`	string	non	URL de callback. Force le mode `webhook`.
`timeoutMs`	number	non	Attente max en ms pour `sync`/`webhook`. Défaut depuis les paramètres, max 120 000.

Mode sync

Long-poll jusqu'à la réponse de l'agent ou le timeout. Réponse (200) :

{
  "ok": true,
  "mode": "sync",
  "chatId": "client-42",
  "ticketId": "550e8400-e29b-41d4-a716-446655440000",
  "replies": [
    { "type": "message", "text": "Warranty is 24 months...", "markdown": false },
    { "type": "attachment", "filename": "warranty.xlsx", "mime": "...", "base64": "..." }
  ]
}

replies est un tableau. Les tableaux Markdown peuvent être renvoyés en pièces jointes XLSX.

Mode async

Le serveur renvoie immédiatement 202. Les réponses s'accumulent dans un buffer et sont vidées via GET /api/v1/messages/:chatId.

{
  "ok": true,
  "mode": "async",
  "chatId": "client-42",
  "ticketId": "550e8400-...",
  "drainUrl": "/api/v1/messages/client-42"
}

Mode webhook

Le serveur renvoie 202 et POST plus tard sur webhookUrl avec une signature HMAC-SHA256 :

X-Cradle-Signature: sha256=<hex>

Le secret par défaut est la clé API si webhookSecret n'est pas configuré dans les paramètres du canal.

GET /api/v1/messages/:chatId

Vide les réponses accumulées pour un chat.

Param	Type	Description
`:chatId`	string	Même ID utilisé dans POST
`wait`	number	`0` renvoie immédiatement ; une valeur supérieure à `0` fait un long-poll jusqu'à 60 000 ms

Réponse :

{
  "ok": true,
  "chatId": "client-42",
  "replies": [ { "type": "message", "text": "..." } ]
}

Un tableau replies vide n'est pas une erreur.

Rate limits

Défaut : 120 requêtes / minute / (IP + clé).

Activer le canal

Dans l'application de bureau : Intégrations → HTTP API :

Générez une clé API (au moins 16 caractères pour la migration legacy, ou utilisez une clé scopée admin:* depuis le CLI).
Choisissez bindHost :
- 127.0.0.1 — processus locaux uniquement.
- 0.0.0.0 — accès LAN (n'ouvrez le pare-feu qu'aux hôtes de confiance).
Sauvegardez et démarrez.

Sur un serveur headless, le canal API est activé par défaut après cradle server init.

Canal HTTP API

On this page