Skip to content

Developers

Connect your applications to your Belowdecks instance

A documented REST API, an MCP server and signed webhooks, in the Passerelle and Flotte plans. Your applications launch agents, follow their work and collect the results, within the same guardrails as your team.

Entry points

Every system connects through the protocol it already speaks

A business application uses the REST API and an assistant uses MCP, under the same rules. The API, the instance’s MCP server and webhook triggers are part of the Passerelle and Flotte plans. Elsewhere on this site, the instance is called your Belowdecks workspace, collections are lists, functions are automatic tasks and cards are approval requests.

  • REST API v1

    Launch an agent, follow its run, collect what it delivers. Your instance publishes the OpenAPI 3.1 specification and browsable documentation.

  • MCP server

    Any MCP-capable assistant can launch agents, answer their questions, call functions, and read and write your collections.

  • Signed webhooks

    Your system hears about every milestone, with an HMAC signature, automatic retries and a delivery log you can replay.

  • Webhook triggers

    Each trigger has its own URL. It can check the sender’s signature and filter events by header or by body.

  • Collections

    Your CRM or ERP writes through the API into the collections your agents read back. If a single row doesn’t match the schema, nothing is written.

  • Functions

    Named code you call directly: the result comes back in the same request, with no queue and no AI token cost.

Examples

What you’ll write on day one

Replace hub.example.com with your instance’s domain, and $BELOWDECKS_TOKEN with an access token created for your application.

A webhook signature covers the timestamp and the raw body of the delivery. Check it before any decoding, in constant time, and reject deliveries that are too old.

Your instance’s OpenAPI 3.1 specification describes every route. Generate a client for your language from it, and regenerate it when the API changes, instead of maintaining a hand-written wrapper.

bash
# Launch the agent. The 202 response returns task_id and the URLs to follow the run.
TASK_ID=$(curl -s -X POST "https://hub.example.com/api/v1/agents/quotes/run" \
  -H "Authorization: Bearer $BELOWDECKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input":{"request":"R-4821"}}' | jq -r '.task_id')

# Follow the run live (SSE stream).
curl -N -H "Authorization: Bearer $BELOWDECKS_TOKEN" \
  "https://hub.example.com/api/v1/runs/$TASK_ID/stream"

Following a run

The life of a run launched over the API

Runs are asynchronous. You launch one, then follow the work in whatever way fits your system.

  1. 1

    You launch it

    One POST to the agent, with its inputs. The response comes back immediately with the run ID and the URLs to follow it. An idempotency key stops a network retry from starting the work twice.

  2. 2

    You follow it, your way

    Polling with a cursor, an SSE stream, signed webhooks or a WebSocket channel: all four carry the same events. The cursor and the SSE id are the same number, so you can switch methods without missing an event.

  3. 3

    The agent asks a question

    When it can’t decide on its own, the agent stops and asks. The question arrives on the stream and by webhook. Your application collects the answer, from someone on your team for example, and sends it through the API; the agent then resumes its session.

  4. 4

    You collect the result

    The run ends with a summary, the tokens used, the files it delivered and a verdict: Delivered, Partial or Blocked. Runs launched over the API work in a disposable workspace, so collect what matters at the end.

Access and limits

Every API client gets its own scope and rules

An API client stands for one specific application, such as your customer portal or your ERP. An administrator of your instance creates it, or the Belowdecks team does at setup. It sees a single project and only what you grant it.

  • One project per API client

    Each API client is bound to one project. Outside it, the client reaches only the shared functions and collections granted to it; anything else returns 404 rather than 403, so the API doesn’t reveal what exists elsewhere.

  • A request rate per client

    For each client, a maximum number of requests per minute protects your instance from an application that runs out of control.

  • Confirmation cards for important actions

    What an agent receives, such as an email or the content of a request, reaches the model as text to read, which lowers the risk of a hidden instruction without removing it. An important action can therefore be set up to wait for a confirmation card, approved by someone designated in your company or by an instance administrator.

  • A log of every call

    Every request goes into the audit log, and token usage can be read per agent. You know who launched what, and what each run consumed.

  • Two levels of token

    A client token launches agents in its project and manages nothing. An administration token, issued from the profile of an instance administrator, drives the instance itself: projects, agents, skills and secrets. A secret can be written through the API, but its value never comes back.

  • A master switch

    While the instance is paused, every launch request returns 423, and nothing starts until it resumes.

Engine room

Three engines, and the tools you give them

Agents work on real command-line engines. You give them tools and know-how without changing the software.

A choice of three engines

Claude Code by Anthropic, Codex by OpenAI, or pi, which works with several model providers. Engine and model are chosen per agent.

MCP servers for your agents

Add an MCP server to a project and its agents can use its tools: an internal API, a browser, an online service. You paste its configuration, then test the connection.

Functions in bash, Python, Node or PHP

Named code, versioned on every change and tried on examples before it’s approved. A function can call others, wake an agent, and read or write a collection.

Skills written in Markdown

An agent’s know-how is written in plain text, in a SKILL.md file. The agent reads it when the task calls for it.

Let’s talk about the system you want to connect

Tell us what it needs to send and receive. A free 20-minute first call is enough to see whether Belowdecks fits; the diagnostic then works out how to connect it to your instance.