Developers

Connect your applications to your Belowdecks instance

A documented REST API, an MCP server, signed webhooks and a script tag. 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, an assistant uses MCP, a website uses a script tag. They all reach the same instance, under the same rules.

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.
Assistant on your website

One script tag and a list of allowed origins. Each end customer sees only their own conversation.
Conversations in your app

Threads grouped by end customer, an access token that sees only that person’s threads, and the same confirmation cards.
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"

// Check a Belowdecks webhook on the raw body, before any JSON decoding.
function belowdecksSignatureIsValid(string $rawBody, array $headers, string $secret): bool
{
    $timestamp = (int) ($headers['belowdecks-timestamp'] ?? 0);
    $signature = (string) ($headers['belowdecks-signature'] ?? '');

    // Reject a stale delivery: it may have been captured and replayed.
    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/your-key.js" async></script>

{
  "mcpServers": {
    "belowdecks": {
      "url": "https://hub.example.com/mcp/v1",
      "headers": { "Authorization": "Bearer <your client token>" }
    }
  }
}

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
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
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
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 your operator for example, and sends it through the API; the agent then resumes its session.
4
You collect the result

The run ends with a summary, its cost, 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 budget

An API client stands for one specific application, such as your customer portal or your ERP. Your operator creates it in your instance, or the Belowdecks team does at setup. It sees a single project and never spends more than you allow it.

One project per API client

Each API client is bound to one project. Anything outside it returns 404 rather than 403, so the API doesn’t reveal what exists elsewhere.
Caps on cost and rate

For each client: a cap per run, a daily and a monthly budget, and a limit on concurrent runs and on requests per minute. The remaining budget also caps every run.
Tokens bound to one end customer

Your back end exchanges its token for one bound to a single person, usually an end customer using your application, valid for an hour by default. That token reaches only that person’s conversations.
Cards for binding actions

What an end customer types reaches the model as data to handle. That precaution lowers the risk of a hidden instruction without removing it. In a conversation, a binding action therefore waits for a card. Depending on the approval regime, it is confirmed by the end customer for their own request, by someone designated in your company, or by the operator.
A log of every call

Every request goes into the audit log, and usage can be read per agent. You know who launched what, and what it cost.
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, such as your operator, 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. During the diagnostic, we’ll work out together how to connect it to your instance.

Talk about your integration How your data is protected

Connect your applications to your Belowdecks instance

Every system connects through the protocol it already speaks

REST API v1

MCP server

Signed webhooks

Webhook triggers

Assistant on your website

Conversations in your app

Collections

Functions

What you’ll write on day one

The life of a run launched over the API

You launch it

You follow it, your way

The agent asks a question

You collect the result

Every API client gets its own scope and budget

One project per API client

Caps on cost and rate

Tokens bound to one end customer

Cards for binding actions

A log of every call

Two levels of token