API overview

Everything the dashboard and the openship CLI can do is a call to the same HTTP API: create projects, trigger deployments, attach domains, read analytics, manage backups. It's a plain JSON API built on Hono, so you can drive it from a script, a CI job, or an AI agent exactly the way the first-party clients do.

Authentication

A request proves who it is in exactly one of four ways. Openship checks for a Bearer token first, then a session cookie, then the loopback fallback (only if that mode is enabled).

curl https://your-host/api/projects \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Permissions

Once you're authenticated, every route runs one permission check. Each route declares a tag of the form resource:action — project:read, domain:write, deployment:admin — and sub-resources add a middle segment (project:service:write). The action lines up with the HTTP method: read (GET one), write (POST/PUT/PATCH), admin (DELETE and destructive), list (GET a collection).

Access is decided per organization. Openship resolves which org you mean from the X-Organization-Id header (falling back to your session default), then checks your role there — owner, admin, member, or restricted (grant-only). Openship refuses to boot if any route is missing a tag, so there is no accidentally unprotected endpoint. The per-endpoint tables on the module pages list the tag for every route; see Permissions & roles for the full model.

Rate limits

The whole /api surface is rate-limited. Unauthenticated requests fall under a per-IP default; authenticated requests get a more generous per-user budget. Some route groups carry a tighter or looser named policy. Limits are per rolling minute.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. /api/health is never limited (load balancers and SSR poll it).

Error shape

Errors come back as JSON with a stable shape: a human error message and, for typed failures, a machine code. Validation failures add a field-level details map.

{ "error": "This access token is read-only", "code": "TOKEN_READ_ONLY" }

Route groups & availability

Routes are mounted per module. Most exist in every deploy mode; a handful are self-hosted-only (they touch the host filesystem, SSH, or local setup and are never loaded in cloud mode), and the cloud gateway swaps its route set by mode.

Module reference