Développeurs
Brancher vos applications sur votre instance Belowdecks
Une API REST documentée, un serveur MCP, des webhooks signés et une balise de script. Vos applications lancent des agents, suivent leur travail et récupèrent les résultats, avec les mêmes garde-fous que votre équipe.
Points d’entrée
Chaque système se branche par le protocole qu’il connaît déjà
Une application métier passe par l’API REST, un assistant par MCP, un site web par une balise de script. Tous arrivent dans la même instance, sous les mêmes règles.
-
API REST v1
Lancez un agent, suivez son exécution, récupérez ses livrables. Votre instance publie la spécification OpenAPI 3.1 et une documentation à parcourir.
-
Serveur MCP
Un assistant compatible MCP lance des agents, répond à leurs questions, appelle des fonctions, lit et alimente vos collections.
-
Webhooks signés
Votre système est prévenu à chaque jalon, avec une signature HMAC, des nouvelles tentatives automatiques et un journal des livraisons que vous pouvez rejouer.
-
Déclencheurs par webhook
Chaque déclencheur a sa propre adresse. Il peut vérifier la signature de l’expéditeur et filtrer les événements par en-tête ou par contenu.
-
Assistant sur votre site
Une balise de script et la liste des adresses autorisées. Chaque client final ne voit que sa propre conversation.
-
Conversations dans votre application
Des fils rangés par client final, un jeton d’accès limité aux fils de cette personne et les mêmes cartes de confirmation.
-
Collections
Votre logiciel de suivi des clients ou votre PGI écrit par l’API dans les collections que vos agents relisent. Si une ligne ne respecte pas le schéma, rien n’est écrit.
-
Fonctions
Du code nommé que vous appelez directement : la réponse revient dans la même requête, sans file d’attente ni coût de jetons d’IA.
Exemples
Ce que vous écrirez le premier jour
Remplacez hub.example.com par l’adresse de votre instance, et $BELOWDECKS_TOKEN par un jeton d’accès créé pour votre application.
La signature d’un webhook couvre l’horodatage et le corps brut de la livraison. Vérifiez-la avant tout décodage, en temps constant, et refusez une livraison trop ancienne.
La spécification OpenAPI 3.1 de votre instance décrit chaque route. Générez-en le client de votre langage, et régénérez-le quand l’API évolue, au lieu d’entretenir une couche écrite à la main.
# Lancer l'agent. La réponse 202 donne task_id et les adresses de suivi.
TASK_ID=$(curl -s -X POST "https://hub.example.com/api/v1/agents/soumissions/run" \
-H "Authorization: Bearer $BELOWDECKS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"input":{"demande":"D-4821"}}' | jq -r '.task_id')
# Suivre l'exécution en direct (flux SSE).
curl -N -H "Authorization: Bearer $BELOWDECKS_TOKEN" \
"https://hub.example.com/api/v1/runs/$TASK_ID/stream"// Vérifier un webhook de Belowdecks, sur le corps brut, avant tout décodage.
function belowdecksSignatureIsValid(string $rawBody, array $headers, string $secret): bool
{
$timestamp = (int) ($headers['belowdecks-timestamp'] ?? 0);
$signature = (string) ($headers['belowdecks-signature'] ?? '');
// Une livraison trop ancienne est refusée : elle peut avoir été capturée.
if (abs(time() - $timestamp) > 300) {
return false;
}
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}<script src="https://hub.example.com/embed/votre-cle.js" async></script>{
"mcpServers": {
"belowdecks": {
"url": "https://hub.example.com/mcp/v1",
"headers": { "Authorization": "Bearer <votre jeton client>" }
}
}
}Suivi des exécutions
La vie d’une exécution lancée par l’API
Une exécution est asynchrone. Vous la lancez, puis vous suivez le travail par le moyen qui convient à votre système.
- 1
Vous lancez
Un POST sur l’agent, avec ses paramètres. La réponse arrive tout de suite avec l’identifiant de l’exécution et les adresses pour la suivre. Une clé d’idempotence empêche qu’une nouvelle tentative réseau lance le travail deux fois.
- 2
Vous suivez, à votre façon
Interrogation périodique avec un curseur, flux SSE, webhooks signés ou canal WebSocket : les quatre transportent les mêmes événements. Le curseur et l’identifiant SSE sont le même nombre, donc vous changez de méthode sans perdre un événement.
- 3
L’agent pose une question
Quand il ne peut pas décider seul, l’agent s’arrête et demande. La question arrive dans le flux et par webhook. Votre application recueille la réponse, par exemple celle de votre opérateur, et la transmet par l’API; l’agent reprend alors sa session.
- 4
Vous récupérez le résultat
L’exécution se termine avec un résumé, son coût, les fichiers livrés et un verdict : Livré, Partiel ou Bloqué. Les exécutions lancées par l’API travaillent dans un espace jetable, alors récupérez ce qui compte à la fin.
Accès et limites
Chaque accès a son territoire et son budget
Un accès d’API représente une application précise, comme votre portail client ou votre PGI. Votre opérateur le crée dans votre instance, ou l’équipe Belowdecks à la mise en place. Il ne voit qu’un projet et ne dépense jamais plus que ce que vous lui accordez.
-
Un seul projet par accès
Chaque accès d’API est lié à un projet. Toute ressource hors de ce projet lui répond 404 plutôt que 403, pour que l’API ne révèle pas ce qui existe ailleurs.
-
Des plafonds de coût et de cadence
Pour chaque accès : un plafond par exécution, un budget quotidien et un budget mensuel, un nombre maximal d’exécutions simultanées et de requêtes par minute. Le budget restant borne aussi chaque exécution.
-
Des jetons liés à un client final
Votre serveur échange son jeton contre un jeton lié à une seule personne, en général un client final qui utilise votre application, valable une heure par défaut. Ce jeton n’atteint que les conversations de cette personne.
-
Les cartes pour les gestes qui engagent
Ce qu’un client final écrit est transmis au modèle comme une donnée à traiter. Cette précaution réduit le risque d’une consigne cachée sans l’éliminer. Dans une conversation, une action engageante attend donc une carte. Selon le régime d’approbation, elle est confirmée par le client final lui-même pour sa propre demande, par une personne désignée de votre entreprise ou par l’opérateur.
-
Un journal de chaque appel
Chaque requête est inscrite au journal d’audit, et la consommation se lit par agent. Vous savez qui a lancé quoi, et combien cela a coûté.
-
Deux niveaux de jeton
Un jeton client lance des agents dans son projet et ne gère rien. Un jeton d’administration, émis depuis le profil d’un administrateur de l’instance, comme votre opérateur, pilote l’instance : projets, agents, compétences et secrets. Un secret s’écrit par l’API, mais sa valeur ne revient jamais.
-
Un interrupteur général
Quand l’instance est en pause, chaque lancement répond 423, et rien ne démarre avant la reprise.
Salle des machines
Trois moteurs, et les outils que vous leur donnez
Les agents travaillent avec de vrais moteurs en ligne de commande. Vous leur ajoutez des outils et du savoir-faire sans toucher au logiciel.
Trois moteurs au choix
Claude Code d’Anthropic, Codex d’OpenAI ou pi, qui accepte plusieurs fournisseurs de modèles. Le moteur et le modèle se choisissent pour chaque agent.
Des serveurs MCP pour vos agents
Ajoutez un serveur MCP à un projet, et ses agents disposent de ses outils : une API interne, un navigateur, un service en ligne. Vous collez sa configuration, puis vous testez la connexion.
Des fonctions en bash, Python, Node ou PHP
Du code nommé, versionné à chaque modification et essayé sur des exemples avant d’être approuvé. Une fonction peut en appeler d’autres, réveiller un agent, lire ou écrire une collection.
Des compétences en Markdown
Le savoir-faire d’un agent s’écrit en texte simple, dans un fichier SKILL.md. L’agent le lit quand la tâche le demande.
Parlons du système que vous voulez brancher
Dites-nous ce qu’il doit envoyer et recevoir. Au diagnostic, nous voyons ensemble comment le relier à votre instance.