> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/api-reference.md). # API reference ## API Reference The canonical OpenAPI contract is published at [`GET /openapi.yaml`](https://warrant-api-production.up.railway.app/openapi.yaml). ### Authentication | Surface | Header | | -------------------- | --------------------------------------------------------------------------------------------- | | Agent action API | `Authorization: Bearer ` or `X-Warrant-API-Key: ` | | Approval API | `Authorization: Bearer ` or `X-Warrant-API-Key: ` | | Admin API | `X-Warrant-Admin-Key: ` | | Hosted dashboard API | `warrant_session` HttpOnly cookie; `X-Warrant-CSRF` is required for hosted dashboard writes. | ### Endpoints | Method | Path | Auth | Purpose | | -------------------- | ------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------ | | `GET` | `/health` or `/v1/health` | None | Health probe. | | `GET` | `/v1/ready` | None | Database readiness probe. | | `GET` | `/metrics` | None | Prometheus request metrics. | | `GET` | `/app` or `/app/*` | None | Hosted application dashboard and client-side routes. | | `GET` | `/admin` | None | Operator admin console shell. | | `GET` | `/openapi.yaml` | None | Fetch the OpenAPI contract. | | `GET` | `/schemas/{name}.schema.json` | None | Fetch JSON Schema contracts. | | `GET` | `/v1/policy-templates` | None | List built-in starter policies and example proposals. | | `POST` | `/v1/accounts/signup` | None | Create hosted account, organization, default tenant, and first agent key. | | `POST` | `/v1/accounts/login` | None | Create hosted dashboard session. | | `GET` | `/v1/accounts/session` | Hosted Session | Fetch hosted dashboard session profile. | | `POST` | `/v1/accounts/logout` | Hosted Session | Clear hosted dashboard session. | | `GET` | `/v1/accounts/tenants` | Hosted Session | List dashboard tenants for the session user. | | `POST` | `/v1/accounts/tenants` | Hosted Session + CSRF | Create an isolated application from a policy template and return its first agent key once. | | `POST` | `/v1/accounts/tenants/{tenant_id}/api-keys` | Hosted Session | Mint an agent or approver key for an owned tenant. | | `GET` | `/v1/accounts/tenants/{tenant_id}/api-keys` | Hosted Session | List owned tenant key metadata. | | `POST` | `/v1/accounts/tenants/{tenant_id}/api-keys/{key_id}/revoke` | Hosted Session | Revoke an owned tenant key. | | `GET` | `/v1/accounts/tenants/{tenant_id}/policy` | Hosted Session | Fetch a dashboard tenant policy. | | `PUT` | `/v1/accounts/tenants/{tenant_id}/policy` | Hosted Session | Replace policy for an owned tenant. | | `GET` | `/v1/accounts/tenants/{tenant_id}/policy/revisions` | Hosted Session | List dashboard tenant policy revisions. | | `GET`, `PUT` | `/v1/accounts/tenants/{tenant_id}/catalog` | Hosted Session | Fetch or revise the reviewed operation catalog. | | `GET` | `/v1/accounts/tenants/{tenant_id}/catalog/revisions` | Hosted Session | List catalog revision history. | | `POST` | `/v1/accounts/tenants/{tenant_id}/policy/check` | Hosted Session | Dry-run a proposal against current or draft tenant policy. | | `GET` | `/v1/accounts/tenants/{tenant_id}/actions?status=&limit=` | Hosted Session | List dashboard tenant action history. | | `GET` | `/v1/accounts/tenants/{tenant_id}/approvals` | Hosted Session | List held tenant actions pending approval. | | `GET` | `/v1/accounts/tenants/{tenant_id}/actions/{action_id}` | Hosted Session | Fetch a dashboard tenant action trace. | | `GET` | `/v1/accounts/tenants/{tenant_id}/actions/{action_id}/audit-export` | Hosted Session | Export a dashboard tenant action audit record. | | `POST` | `/v1/accounts/tenants/{tenant_id}/actions/{action_id}/approve` | Hosted Session + CSRF | Approve a held action as a tenant owner. | | `POST` | `/v1/accounts/tenants/{tenant_id}/actions/{action_id}/reject` | Hosted Session + CSRF | Reject a held action as a tenant owner without execution. | | `GET` | `/v1/integration` | Agent or Approver | Validate a tenant key and return endpoint, policy, example, and snippet context. | | `GET` | `/v1/tenants` | Admin | List tenants and current policies. | | `POST` | `/v1/tenants` | Admin | Create tenant and mint first agent key with an integration bundle. | | `POST` | `/v1/tenants/{tenant_id}/api-keys` | Admin | Mint an agent or approver key with an integration bundle. | | `GET` | `/v1/tenants/{tenant_id}/api-keys` | Admin | List key metadata. | | `POST` | `/v1/tenants/{tenant_id}/api-keys/{key_id}/revoke` | Admin | Revoke a tenant key. | | `POST` | `/v1/policies/validate` | Admin | Validate and normalize a policy without mutating tenants. | | `POST` | `/v1/policies/verify` | Admin | Run bounded reachability verification for forbidden outcomes. | | `GET` | `/v1/tenants/{tenant_id}/policy` | Admin | Fetch tenant policy. | | `PUT` | `/v1/tenants/{tenant_id}/policy` | Admin | Replace tenant policy for future proposals. | | `GET` | `/v1/tenants/{tenant_id}/policy/revisions` | Admin | List tenant policy revision history. | | `GET`, `POST`, `PUT` | `/v1/tenants/{tenant_id}/catalog` | Admin | Fetch, create, or revise the reviewed operation catalog. | | `GET` | `/v1/tenants/{tenant_id}/catalog/revisions` | Admin | List catalog revisions. | | `GET` | `/v1/tenants/{tenant_id}/catalog/revisions/{revision}` | Admin | Fetch one catalog revision. | | `POST` | `/v1/tenants/{tenant_id}/policy/check` | Admin | Dry-run a proposal against current or draft policy. | | `POST` | `/v1/tenants/{tenant_id}/policy/admit` | Admin | Enumerate strict-admission coverage, catalog, schema, actuator, and idempotency holes. | | `POST` | `/v1/tenants/{tenant_id}/policy/verify` | Admin | Verify live or draft tenant policy; persist a hash-bound, optionally signed report. | | `GET` | `/v1/tenants/{tenant_id}/verification` | Admin | List stored verification reports with live-policy binding. | | `POST` | `/v1/actions` | Agent | Submit an action proposal. | | `GET` | `/v1/actions?status=&limit=` | Agent | List recent tenant actions. | | `GET` | `/v1/approvals` | Approver | List held actions for the approver key's tenant. | | `POST` | `/v1/actions/{action_id}/approve` | Approver | Approve a held proposal and execute it. | | `POST` | `/v1/actions/{action_id}/reject` | Approver | Reject a held proposal without execution. | | `GET` | `/v1/actions/{action_id}` | Agent | Fetch the audited action trace. | | `GET` | `/v1/actions/{action_id}/audit-export` | Agent | Export a proof-bearing audit record. | Hosted account routes are present only when the deployment enables `WARRANT_HOSTED_ACCOUNTS`. Agent, approver, and admin API-key routes are unchanged. ### Action Status Values `received`, `allowed`, `pending_approval`, `approved`, `execution_pending`, `executing`, `denied`, `executed`, `execution_failed`, `outcome_unknown` ### Status Codes | Status | Meaning | | ------ | -------------------------------------------------------------------------- | | `200` | Request succeeded. | | `201` | Tenant or key created. | | `202` | Execution is durably queued/leased/retrying; poll the returned action URL. | | `400` | JSON, proposal, policy, or key request validation failed. | | `401` | Required API key is missing. | | `403` | API key is invalid or revoked. | | `404` | Tenant, key, or action was not found. | | `409` | Proposal id conflict, tenant conflict, or action is not approvable. | | `413` | Request body exceeds the configured limit. | | `429` | Request rate limit exceeded. Retry after the `Retry-After` header delay. | | `503` | Readiness failed because durable storage is unavailable. | A `202` polling URL is read-only. Fetching it does not execute a retry or reclaim an expired lease. The current release requires a deployment worker extension to enumerate due jobs and call `Gateway.run_execution_job` for their action IDs; see Execution jobs and retries. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.