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 post-signup operator-client pairing for coding agents.
Authentication
Most endpoints require an authenticated session via the standard /api/auth/login flow, which sets a session cookie. Operator clients are paired after a human account exists: the agent starts a short-lived pairing session, the signed-in user approves it in the browser, and the agent proves possession of its key before receiving a scoped trusted-client bearer token.
POST /api/auth/login— sign in with email + password (or recovery kit).POST /api/auth/signup— create a new platform user, or enter the signup queue when approvals are required.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/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 / POST | /api/registry/companies/:id/credentials | List generic credential metadata or submit a package-native credential document. |
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 | /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 and runtime status. |
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 | 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. |
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.