Home / Docs / Control-plane API
Control-plane API reference
The control plane coordinates recovery jobs across your org: it issues signed jobs to the customer-side runner and stores metadata, evidence, and audit — never customer rows. All endpoints are JSON over HTTPS under /v1.
Authentication
Every request carries a bearer token: Authorization: Bearer <token>. A missing or blank token returns 401; a valid token whose role lacks the route's capability returns 403. Tokens are scoped to one org, and every response is filtered to that org.
Roles and capabilities
| Capability | Grants | Roles |
|---|---|---|
read | List/read jobs, evidence, audit | admin, operator, auditor |
create-job | Create recovery jobs | admin, operator |
approve | Approve a plan hash | admin, operator |
manage-org | Create connections, invite users | admin |
Auditor accounts can read evidence and audit but cannot create or approve mutations — separation of duties by design.
Endpoints
| Method & path | Capability | Description |
|---|---|---|
GET /v1/jobs | read | List jobs for the org. |
POST /v1/jobs | create-job | Create a job (analyze, report, extract, diff, plan, merge, erase). |
GET /v1/jobs/{id} | read | Fetch one job: type, state, plan hash, counts. |
POST /v1/jobs/{id}/approve | approve | Approve the job's exact plan hash, unblocking a merge or erase. |
GET /v1/jobs/{id}/evidence | read | Retrieve the signed evidence artifact for a completed job. |
GET /v1/audit | read | Append-only audit log of jobs, approvals, and access. |
POST /v1/connections | manage-org | Create a runner connection; mints a one-time registration token. |
POST /v1/users | manage-org | Invite a user to the org with a role. |
Billing events arrive on a separate Stripe webhook endpoint whose payload signature is verified before processing.
Job lifecycle
Jobs move through a strict state machine; illegal transitions are refused:
pending → dispatched → running → awaiting_approval → approved → done
↘ (any stage) → failedRead-type jobs (analyze, report, extract, diff, plan) run to done without approval. Mutating jobs (merge, erase) pause at awaiting_approval until a second authorized user approves the exact plan hash via POST /v1/jobs/{id}/approve.
The runner does the data work. The control plane never connects to your database. It signs a job; the outbound-only runner in your VPC executes it and returns metadata and signed evidence references. See the security model.
Get an org and a token
The Control plan provisions your org, runner connection, and roles. Start with a drill to see the job flow end to end.
Talk to us