Aller au contenu

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.

bash
# 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"

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. 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. 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. 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. 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.