Overview
The Exocorp platform exposes a REST API for managing exocorps programmatically — the registry (your own exocorps), the dashboard (rollup views), admin (platform-owner operations), runtime (per-exocorp state), and the operator-client API used by coding agents during signup.
Authentication
Most endpoints require an authenticated session via the standard /api/auth/login flow, which sets a session cookie. The operator-clients API uses a two-token signup flow: a draft access token returned at draft creation, then a trusted-client bearer token after redeem.
POST /api/auth/login— sign in with email + password (or recovery kit).POST /api/auth/signup— create a new platform user and apply signup credit.POST /api/auth/logout— terminate the session.GET /api/auth/me— current identity, roles, and platform-owner status.
The registry — your own exocorps
The registry endpoints are scoped to exocorps you own or are a member of. Used by both the dashboard UI and external tooling.
| Method | Path | Purpose |
|---|---|---|
GET | /api/registry/my-companies | Your fleet — every exocorp you can access. |
GET | /api/registry/companies/:id | Detail and current status of one exocorp. |
POST | /api/registry/companies/:id/provision | Provision (or start) the runtime. |
POST | /api/registry/companies/:id/update | Apply a release update. |
POST | /api/registry/companies/:id/restart | Restart from last successful provision. |
POST | /api/registry/companies/:id/stop | Halt the runtime. |
GET | /api/registry/companies/:id/bindings | Provider credential bindings. |
GET / POST | /api/registry/companies/:id/draft | Read or save the company draft. |
GET | /api/registry/companies/:id/update-handshake | Evaluate whether an update is available. |
GET / POST | /api/registry/provider-secrets | Manage provider credentials at account scope. |
GET | /api/registry/company-releases/current | Currently published release manifest. |
GET | /api/registry/company-releases/catalog | Catalog of available release versions. |
The dashboard — rollup views
| Method | Path | Purpose |
|---|---|---|
GET | /api/dashboard/summary | Fleet overview: companies, status, provider-credential coverage. |
Admin — platform-owner operations
Admin endpoints require platform-owner role. Most lifecycle actions live under /api/admin/companies/:id/actions (see Lifecycle controls for the full action surface).
| Method | Path | Purpose |
|---|---|---|
GET | /api/admin/companies | All exocorps, with job metadata. |
GET | /api/admin/companies/:id/details | Admin-detailed view of one exocorp. |
GET | /api/admin/companies/:id/runtime | Runtime health and state. |
POST | /api/admin/companies/:id/actions | Pause / resume / update / restart / reprovision / rollback / stop / destroy. |
GET | /api/admin/billing/accounts | All billing accounts and state. |
GET | /api/admin/runtime-stats | Platform-wide runtime metrics. |
Runtime — per-exocorp state
| Method | Path | Purpose |
|---|---|---|
GET | /api/runtime/billing/usage | Per-exocorp usage events. |
GET | /api/runtime/execution-providers/state | Provider health and capacity. |
Operator clients — post-signup agents
Operator-client access is attached after a human signs up and approves the agent from an authenticated browser handoff. Public agent-first signup is not supported. The public routing skill is hosted at /SKILL.md, and post-signup agent guidance is hosted at /skills/connect-agent.md.
Errors and conflicts
API endpoints return structured errors with HTTP status codes that mean what they say:
- 400 — Validation error (bad input, missing required field, bad JSON).
- 401 — Authentication required.
- 403 — Forbidden (insufficient role, e.g. trying to hit an admin endpoint without platform-owner).
- 404 — Resource not found.
- 409 — Conflict — the action can’t be performed in the current state (e.g. already provisioning, already running, missing price book, release lookup failed).
- 500 — Internal error. The platform records the trace; you can usually retry.