The control-plane API is the transport the CLI speaks to a server. Most operators
never call it directly — the boatramp subcommands wrap it — but it is a stable,
documented surface for building your own tooling. This page lists the endpoints;
the CLI reference maps each command onto them.
Base path. Every control-plane endpoint is under /api. Public serving
(host-routed content, /_sites/*, /healthz) is a separate, unauthenticated
surface.
Authentication. A bearer token in Authorization: Bearer <token>. Every
/api/* request is authenticated and authorized, except the handful gated by
their own single-use credential (bootstrap, join, OIDC exchange). The exact
right each endpoint requires is in the
request-to-right mapping.
Bodies. Requests and responses are JSON, except blob upload (raw bytes) and
/api/metrics (Prometheus text).
Errors. A non-2xx status carries a JSON { "error": "..." }. 401 is a
missing or invalid token; 403 is a valid token without the required right.
A project owns sites, functions, and compute, and is the
tenant boundary. Since 0.2.0 every site/function/compute/workflow endpoint has a
project-scoped counterpart under /api/projects/:project/…; the legacy top-level
paths (/api/sites/…, /api/functions/…, /api/compute/…, /api/workflows/…)
target the reserved default project and stay byte-identical to pre-0.2.0.
Method
Path
Purpose
GET
/api/projects
List projects.
POST
/api/projects
Create a project.
GET
/api/projects/:project
Get one project’s record.
DELETE
/api/projects/:project
Delete an empty project (refused while it owns resources or is default).
any
/api/projects/:project/sites/…
Per-project site endpoints — the same shapes as Sites & deployments, scoped to the project.
The subgraph registry, the operation safelist, and the composed supergraph — a
project-owned surface. Top-level paths target the default project;
/api/projects/:project/graphql/… scopes to another project. See
Serve a GraphQL API.
Method
Path
Purpose
PUT/DELETE
/api/graphql/subgraphs/:name
Register (SDL body) / unregister a subgraph; a publish recomposes and is rejected if it doesn’t compose.
PUT
/api/graphql/subgraphs/:name/sql
Register a SQL-backed subgraph by introspecting a site’s managed database.
PUT
/api/graphql/subgraphs/:name/function
Register a function-backed subgraph by introspecting its _service { sdl }.
GET
/api/graphql/supergraph
The composed supergraph (subgraphs, @key entities, root fields).
POST/GET
/api/graphql/safelist
Register a trusted operation (returns its hash) / list the safelist.
DELETE
/api/graphql/safelist/:hash
Remove an operation from the safelist.
A function that self-declares a subgraph auto-registers on deploy; pass
?register_subgraph=false to PUT /api/functions/:name to opt a deploy out. See
Federation.
Model Context Protocol endpoint (streamable-http), for driving this node from an AI agent.
Unlike /api/*, /mcp is gated only by a valid plain bearer (not a specific
right): each MCP tool call is separately re-authorized in-process against the
forwarded token’s scope. On by default; toggle with mcp.enabled
(daemon config). cnf/DPoP tokens are rejected — use a plain
bearer or the stdio transport.