Home / API / Reference
API reference
On this page
Resource model Draft
The API exposes the execution chain as resources. Every resource is scoped to a tenant (organization → workspace → environment); the tenant is part of every URL and every record.
| Resource | Represents | Key fields |
|---|---|---|
tenants | Organization / workspace / environment scope | organization, workspace, environment |
actions | Proposed and executed actions (stages 1–5) | action_id, schema, schema_version, status, inputs_hash |
policies | Versioned policy bundles and their rules | bundle, version, effective_from, rules |
approvals | Human approval requests from require-approval decisions | approval_id, action_id, status, expires_at |
receipts | Evidence receipts (stage 6) | receipt_id, action_id, receipt_hash, prev_receipt_hash |
modules | Registered modules and their manifests | module, version, manifest |
Conventions: identifiers are opaque strings with a short prefix (act_, rcpt_, apr_); timestamps are RFC 3339 UTC; money is integer minor units with an ISO 4217 currency code.
Authentication Draft
- API keys (Draft): long-lived keys scoped to a tenant, sent as
Authorization: Bearer <key>. Keys carry the scopes granted at issuance; scopes cannot be widened without re-issuance. - Service tokens (Draft): short-lived tokens minted for service actors, with an explicit expiry.
- Mutual TLS (Roadmap): planned for module-to-platform traffic; not available in v1.
Keys and tokens are illustrative in every sample on this site. Never commit real credentials. Rotate any credential that appears in logs, evidence, or chat.
Errors Draft
Errors use a single envelope. HTTP status codes follow standard semantics (400 validation, 401 authentication, 403 authorization, 404 not found, 409 conflict, 422 policy denial, 429 rate limit, 5xx platform fault).
code is stable within a Draft revision; the catalog is not final.{
"error": {
"code": "policy_denied",
"message": "Action denied by policy rule 'deny-cross-environment'.",
"details": {
"bundle": "billing-default",
"version": "2.1.0",
"matched_rule": "deny-cross-environment"
},
"request_id": "req_7H2K9Q"
}
}
Pagination Draft
List endpoints use cursor pagination. Pass limit (default 50, max 500) and the opaque cursor from the previous page. Responses carry a page object:
{
"data": [ "...", "..." ],
"page": {
"next_cursor": "eyJvZmZzZXQiOjEwMH0",
"has_more": true
}
}
Endpoints Roadmap
No endpoints are live in v1. The paths below describe the planned surface only. Do not call them; there is nothing listening. Endpoint GA is tracked on the roadmap.
| Method | Planned path | Description | Status |
|---|---|---|---|
POST | /v1/{tenant}/actions | Submit an action proposal (stages 1–4) | Roadmap |
GET | /v1/{tenant}/actions/{id} | Read an action and its execution record | Roadmap |
GET | /v1/{tenant}/actions | List actions (cursor-paginated) | Roadmap |
GET | /v1/{tenant}/receipts/{id} | Read an evidence receipt | Roadmap |
GET | /v1/{tenant}/receipts | List receipts (cursor-paginated) | Roadmap |
POST | /v1/{tenant}/approvals/{id}/decision | Record a human approval decision | Roadmap |
GET | /v1/{tenant}/policies/{bundle} | Read the effective policy bundle | Roadmap |
Related: JavaScript SDK and Python SDK (both Draft) will wrap these endpoints when they go live. Until then, run the quickstart locally.