API Overview

ShipOS exposes two API surfaces: a control plane for managing flags and projects, and an edge for evaluating flags globally in under 50ms. This page covers base URLs, authentication, the execution model, audit, and the shared error shape.

Base URLs

The two surfaces live on different hosts and use different keys. Pick the one that matches what you're doing.

Authentication

The control plane accepts two authentication modes. Dashboard users authenticate with a Supabase session cookie; programmatic clients and agents authenticate with a bearer key.

Session cookie

Dashboard users are authenticated by their Supabase session cookie. Session users may pass ?orgId=<uuid> on any endpoint to act inside another org they belong to; without it, requests default to their first membership.

Bearer key

Programmatic clients send Authorization: Bearer <key>. Which key works where depends on its kind:

Here's a request to list your org's projects using a bearer agent key:

curl https://app.shipos.app/api/v1/projects \
  -H "Authorization: Bearer sos_agt_xxxxxxxxxxxxxxxxxxxx"

Direct execution

A valid credential executes mutations directly, there is no approval or sign-off step. Agent keys (sos_agt_*), admin keys (sos_adm_*), and dashboard sessions all apply changes immediately. Safety comes from two properties that hold for every change: it is audited and it is instantly reversible with the flag's kill switch.

Audit trail

Every mutation writes an audit row atomically with the change, if the write fails, the audit row is never orphaned. Session users are recorded as actor_type: user. Both agent and admin keys are recorded as actor_type: agent, tagged with their key prefix.

Errors

Every error, across both surfaces, uses the same envelope: an error object with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "version_conflict",
    "message": "The config was updated by someone else. Refetch and retry."
  }
}