Développeurs
Brancher vos applications sur votre instance Belowdecks
Une API REST documentée, un serveur MCP et des webhooks signés, dans les formules Passerelle et Flotte. 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 et un assistant par MCP, sous les mêmes règles. L’API, le serveur MCP de l’instance et les déclencheurs par webhook font partie des formules Passerelle et Flotte. Ailleurs sur le site, l’instance s’appelle votre espace Belowdecks, les collections des listes, les fonctions des tâches automatiques et les cartes des demandes de validation.
-
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.
-
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);
}{
"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 d’une personne de votre équipe, 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é, les jetons consommés, les fichiers livrés et un résultat : 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 ses règles
Un accès d’API représente une application précise, comme votre portail client ou votre PGI. Un administrateur de votre instance le crée, ou l’équipe Belowdecks à la mise en place. Il ne voit qu’un projet et ce que vous lui accordez.
-
Un seul projet par accès
Chaque accès d’API est lié à un projet. Hors de ce projet, il n’atteint que les fonctions et les collections partagées qui lui sont accordées; toute autre ressource lui répond 404 plutôt que 403, pour que l’API ne révèle pas ce qui existe ailleurs.
-
Une cadence par accès
Pour chaque accès, un nombre maximal de requêtes par minute protège votre instance d’une application qui s’emballerait.
-
Des cartes de confirmation pour les actions importantes
Ce que reçoit un agent, comme un courriel ou le contenu d’une requête, est transmis au modèle comme du texte à lire, ce qui réduit le risque d’une consigne cachée sans l’éliminer. Une action importante peut donc être réglée pour attendre une carte de confirmation, approuvée par une personne désignée de votre entreprise ou par un administrateur de l’instance.
-
Un journal de chaque appel
Chaque requête est inscrite au journal d’audit, et la consommation en jetons se lit par agent. Vous savez qui a lancé quoi, et ce que chaque exécution a consommé.
-
Deux niveaux de jeton d’accès
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, 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. Un premier échange gratuit de 20 minutes suffit pour voir si Belowdecks s’y prête; le diagnostic établit ensuite comment le relier à votre instance.