API reference
Every public endpoint under /v1, with its purpose and the credential it accepts. Bodies are validated with the same schemas the console uses; a validation failure returns 400 invalid_body with the field errors.
Authentication
Authorization: Bearer cak_… for backend and agent keys, or the console session cookie. “editor+” means the org role must be editor or owner. Machine-to-machine calls should always use a key.
Endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/mandates | Register a mandate (authority, subject, limits, expiry) | backend API key or session (editor+) |
| POST | /v1/operations | Propose an action; 202 + decision. Idempotency-Key honoured | agent or backend key, or session (editor+) |
| GET | /v1/operations/{id} | Operation state, decision reasons, approval, evidence count | any key or session |
| POST | /v1/operations/{id}/decision | Approve / reject with the exact approval digest | session only |
| POST | /v1/observations | Observation mode: report an action the agent took itself; 201 + would-be decision, read-only verification | agent or backend key, or session (editor+) |
| GET | /v1/observations | Observations + summary (?project_id, days, flagged=1) | any key or session |
| GET | /v1/observations/{id} | One observation with its verification state and note | any key or session |
| GET | /v1/projects | List projects | any key or session |
| POST | /v1/projects | Create a project (templates added automatically) | session only |
| POST | /v1/projects/{id}/agent-builds | Register an agent build: version, endpoint_url, auth_header?, response_path?, set_default | backend API key or session (editor+) |
| POST | /v1/projects/{id}/agent-builds/probe | Probe an endpoint with a sample request; nothing stored | backend API key or session (editor+) |
| POST | /v1/projects/{id}/connections/sandbox | Create a simulated-Stripe world + connection | backend API key or session (editor+) |
| POST | /v1/projects/{id}/pause · /unpause | Kill-switch: stop new writes / re-queue held operations | session only |
| GETPUT | /v1/projects/{id}/end-user-caps | Per-end-user rate and spend caps | backend API key or session (editor+) |
| POST | /v1/projects/{id}/connections/stripe | Connect Stripe: restricted key + webhook secret, permissions probed read-only | backend API key or session (editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/rotate | Rotate the key (same Stripe account) and optionally the webhook secret | backend API key or session (editor+) |
| POST | /v1/projects/{id}/connections/{connection_id}/default | Make it the project’s default Guard connection | backend API key or session (editor+) |
| DELETE | /v1/projects/{id}/connections/{connection_id} | Remove (credentials deleted; refused while in use) | backend API key or session (editor+) |
| GETPUTDELETE | /v1/projects/{id}/access-service | Client access service URL + signing secret (secret never returned) | backend API key or session (editor+) |
| POST | /v1/projects/{id}/access-service/test | One signed read for a customer id; shows the state or the exact error | backend API key or session (editor+) |
| POST | /v1/test-runs | Start a suite (repeats 1–5); counts against the plan | backend API key or session (editor+) |
| GET | /v1/test-runs/{id} | Run status, verdict, counts, cost, per-scenario attempts | any key or session |
| GET | /v1/test-runs/{id}/export | ?format=json|csv|pdf | any key or session |
| GET | /v1/test-runs/compare | ?base=&head= — version comparison | any key or session |
| POST | /v1/test-runs/{id}/incidents | Open an incident from a failed run | session only |
| GETPOST | /v1/schedules | Scheduled suites (cron) | backend API key or session (editor+) |
| PATCHDELETE | /v1/schedules/{id} · POST …/run | Edit, delete, run now | backend API key or session (editor+) |
| GETPUT | /v1/guardrails | Rail configuration per project | backend API key or session (editor+) |
| GET | /v1/guardrails/hits | Recent hits (keyset paginated) | any key or session |
| GETPOST | /v1/alert-channels | Slack / email / webhook alerts per project | backend API key or session (editor+) |
| DELETE | /v1/alert-channels/{id} · POST …/test | Remove, send a test alert | backend API key or session (editor+) |
| GETPOST | /v1/incidents | List / create incidents | any key or session |
| POST | /v1/incidents/{id}/transition · /notes | OPEN → ASSIGNED → RESOLVED / ACCEPTED_RISK; journal | session only |
| POST | /v1/architect/drafts · /accept | Draft scenarios from a description; accept the approved ones | backend API key or session (editor+) |
| POST | /v1/redteam/suite | Generate hostile inputs and run them | backend API key or session (editor+) |
| GET | /v1/compliance/export | ?from&to&project_id&format=json|pdf — tamper-evident report | any key or session |
| POST | /v1/compliance/email | Email the compliance PDF | session only |
| GETPOST | /v1/api-keys | List / create keys (backend | agent, per project or org) | session only (owner) |
| GETPUT | /v1/ai-settings · POST …/test | AI mode (off / byok / managed), model, key, spend cap; real metered test call | session only |
| GETPUT | /v1/plan | Plan and usage (PUT only when billing is not configured; otherwise 409 use_billing) | session only (owner) |
| GET | /v1/billing | Billing state: subscribed, status (active / past_due / canceled), renewal, grace end | any key or session |
| POST | /v1/billing/checkout | Start a Stripe Checkout for { plan: test | guard }; returns the URL | session only (owner) |
| POST | /v1/billing/portal | Open the Stripe Customer Portal (cards, invoices, plan change, cancel) | session only (owner) |
| POST | /v1/access-requests | Ask COLVO to unlock a capability | session only |
| POST | /v1/webhooks/stripe/{connectionId} | Signature-verified Stripe intake | stripe-signature |
Pagination
List endpoints that can grow use keyset pagination: ?limit= (max 200) and ?cursor= from the previous response’s next_cursor. Order is newest first and stable while new rows arrive.
Rate limits
Public forms are limited per IP (429 rate_limited). API keys are not rate limited during the pilot beyond plan quotas; abusive traffic is paused per organisation and the owner is told why.