Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Control-plane HTTP API

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.

Conventions

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

Sites & deployments

MethodPathPurpose
GET/api/sitesList sites.
POST/api/sites/:site/deploymentsCreate a deployment from a manifest.
GET/api/sites/:site/deploymentsList a site’s deployments.
GET/api/sites/:site/deployments/:idGet one deployment.
POST/api/sites/:site/deployments/:id/activateMake a deployment the live one.
GET/api/sites/:site/currentThe currently active deployment.
GET/PUT/api/sites/:site/configRead / replace the site config.
GET/PUT/DELETE/api/sites/:site/aliases/:nameManage named aliases.
GET/api/sites/:site/aliasesList aliases.

Blobs

MethodPathPurpose
PUT/api/blobs/:hashUpload a content-addressed blob (raw body; the server verifies the hash).

Domains

MethodPathPurpose
GET/POST/DELETE/api/sites/:site/domains/:host/verificationManage a domain-ownership challenge.
POST/api/sites/:site/domains/:host/verification/checkCheck the challenge.
GET/api/sites/:site/domain-verificationsList pending verifications.

Tokens

MethodPathPurpose
POST/GET/api/tokensMint / list tokens.
DELETE/api/tokens/:idRevoke a token by its id.
POST/api/tokens/bootstrapMint the first admin token with the single-use bootstrap secret.
GET/api/auth/whoamiThe presented token’s own roles.
POST/api/auth/exchangeExchange an OIDC JWT for a short-TTL token (oidc feature).

Cluster

MethodPathPurpose
POST/api/cluster/join-tokenMint a single-use mesh join token.
POST/api/cluster/joinAdmit a joining node presenting a join token.
POST/api/cluster/rotate-keyRotate this node’s mesh key (make-before-break).
POST/api/cluster/revokeRevoke a node from the mesh.

See Manage cluster mesh certificates.

Certificates & cache

MethodPathPurpose
GET/api/certsTLS certificate status.
POST/api/cache/invalidateInvalidate cached responses.

Operations

MethodPathPurpose
GET/POST/api/pruneReport / delete unreferenced deployments.
POST/api/scrubDelete unreferenced blobs.
GET/api/metricsPrometheus exposition (always available).
GET/PUT/api/authz/policyRead / replace the RBAC policy.

Compute

MethodPathPurpose
GET/api/computeList compute workloads.
GET/PUT/DELETE/api/compute/:nameManage one workload.

Requires KVM on the serving host; the control-plane surface is uniform whether or not execution is available. See Run compute workloads.

Per-site observability

Present with the handlers feature.

MethodPathPurpose
GET/api/sites/:site/_boatramp/handlersPer-handler operator stats.
GET/api/sites/:site/_boatramp/logsCaptured guest logs.
GET/api/sites/:site/_boatramp/logs/streamStream logs (SSE).
POST/api/sites/:site/_boatramp/dlqDead-letter-queue operations.

See Observe a running server.

Public (unauthenticated) endpoints

Never token-authenticated. Visitor access control (basic auth / IP rules / rate limit) is applied per-site inside the serving handlers.

MethodPathPurpose
GET/healthzLiveness.
GET/readyzReadiness.
any/ (host-routed)Serve site content, selected by Host — see How a request reaches your site.
any/_sites/<name>/*Serve a site by name (admin/testing). /sites/<name>/* is a deprecated alias.
GET/_deploy/*Serve a deployment by id (an unguessable content-hash capability).