API & MCP Reference

All HTTP endpoints require Authorization: Bearer <token>. Obtain a JWT via POST /api/auth/login:


curl -X POST "https://orb.thomas.md/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

1. Missions & Streaming

Create Mission

POST /api/control/missions


{
  "title": "Verify Pareto proof",
  "project": "verity",
  "workspace_id": "uuid",
  "backend": "antigravity",
  "model_override": "agy-demo",
  "model_effort": "high",
  "placement": "client",
  "remote_node_id": null
}

backend: "claudecode", "codex", "antigravity", "opencode", "grok", or cloud adapters ("hermes", "cursor_cloud", "grok_bot").
placement: Omit for server/fleet execution, or set "client" when Orb Desktop executes the CLI locally.
model_effort: "low", "medium", "high", or "xhigh".

Send Message / Steer

POST /api/control/message


{
  "content": "Follow-up instruction",
  "client_message_id": "uuid"
}

Snapshot & Cursor-Paginated Events

GET /api/control/missions/:id/snapshot: First-paint payload returning mission metadata, latest history events, counts, child missions, and running state.
GET /api/control/missions/:id/events?view=history&limit=200&before_seq=1000: Cursor-paginated event log (view=transcript|trace|history|all, since_seq, before_seq). Returns X-Next-Cursor, X-Page-Max-Sequence, X-Max-Sequence, and X-Has-More headers (X-Orb-Events-Protocol: 1).
GET /api/control/stream?mission=<uuid>: Real-time SSE stream (status, stream_lagged, user_message, assistant_message, thinking, tool_call, tool_result, text_delta, error, mission_status_changed).

Advanced Mission Operations

Endpoint	Method	Description
`/api/control/missions/:id/load`	`POST`	Load mission into active control session
`/api/control/missions/:id/cancel`	`POST`	Cancel running mission
`/api/control/missions/:id/resume`	`POST`	Resume interrupted mission
`/api/control/missions/:id/btw/agent`	`POST`	Launch or continue a `/btw` side-agent session
`/api/control/missions/:id/machine-transfer`	`GET` / `POST`	Inspect inventory, stage blocks, and activate cross-machine mission transfer
`/api/control/missions/:id/cyber`	`GET` / `PATCH`	Read or set Codex Cyber Access (`standard`, `daybreak`, `automatic`)
`/api/control/missions/:id/continuations/cancel`	`POST`	Revoke scheduled mission wake-ups
`/api/control/local-origins`	`POST`	Synchronize offline-started local Orb missions

2. Projects, Situation & Context

Endpoint	Method	Description
`/api/projects/overview`	`GET`	Roster of all projects, active tracks, attention items, and colors
`/api/projects/:slug`	`GET` / `PUT`	Read or update project metadata, color, and settings
`/api/projects/:slug/situation`	`GET`	Canonical bounded read of project state, tracks, and active attempts
`/api/projects/:slug/steers`	`POST`	Enqueue an operator steer for a project controller
`/api/projects/:slug/grant`	`GET` / `POST`	Inspect or update autonomous controller grant
`/api/projects/:slug/context/manifest`	`GET`	Synchronized `@context` file manifest and revisions
`/api/file-resources`	`POST`	Confined workspace and project file reader for Orb’s Files panel
`/api/uploads`	`POST`	Authenticated 20 MiB file/image upload to Core or a target `node_id`

3. Machines, Providers & Routing

Endpoint	Method	Description
`/api/remote-nodes`	`GET`	Fleet node roster, health, disk budgets, and `remote_launch` capabilities
`/api/software`	`GET`	Host CLI versions across Core and `?node=<id>`
`/api/software/updates`	`POST`	Trigger atomic managed CLI update on Core or a node
`/api/ai/providers/cli-proxy-login`	`GET` / `POST` / `DELETE`	Start, complete, or cancel CLIProxyAPI OAuth subscription login
`/api/providers/backend-models`	`GET`	Model catalog across configured backends
`/api/providers/antigravity-models`	`GET`	Workspace-native `agy models` discovery
`/api/model-routing`	`GET` / `POST`	Manage model routing fallback chains and inspect provider health
`/api/cloud/accounts`	`GET`	List connected Cloud Agent accounts (Hermes, Grok Bot, Cursor Cloud)

4. Unified MCP (`sandboxed-mcp` & `/api/mcp`)

sandboxed-mcp is the unified stdio MCP binary used by Hermes (coordinator profile), mission harnesses (executor profile), and operators (operator profile). It talks to Core over /api/mcp:

POST /api/mcp/session: Exchanges an owner/launcher credential for a 1-hour scoped mcp1. token.
POST /api/mcp/renew: Renews an active session token with identical privileges.
GET /api/mcp/capabilities: Lists tools permitted for the session’s profile (executor, coordinator, or operator).
POST /api/mcp/call: Executes a tool call. All mutations require an idempotency_key and return a durable action receipt (get_action, cancel_action, reconcile_action).