Home / API / Reference

API reference

Draft The conventions below are documented but may change before 1.0. There are no live endpoints in v1 — do not call any URL 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.

ResourceRepresentsKey fields
tenantsOrganization / workspace / environment scopeorganization, workspace, environment
actionsProposed and executed actions (stages 1–5)action_id, schema, schema_version, status, inputs_hash
policiesVersioned policy bundles and their rulesbundle, version, effective_from, rules
approvalsHuman approval requests from require-approval decisionsapproval_id, action_id, status, expires_at
receiptsEvidence receipts (stage 6)receipt_id, action_id, receipt_hash, prev_receipt_hash
modulesRegistered modules and their manifestsmodule, 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).

Illustrative referenceError envelope. The 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:

Illustrative referencePagination envelope for list responses.
{
  "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.

MethodPlanned pathDescriptionStatus
POST/v1/{tenant}/actionsSubmit an action proposal (stages 1–4)Roadmap
GET/v1/{tenant}/actions/{id}Read an action and its execution recordRoadmap
GET/v1/{tenant}/actionsList actions (cursor-paginated)Roadmap
GET/v1/{tenant}/receipts/{id}Read an evidence receiptRoadmap
GET/v1/{tenant}/receiptsList receipts (cursor-paginated)Roadmap
POST/v1/{tenant}/approvals/{id}/decisionRecord a human approval decisionRoadmap
GET/v1/{tenant}/policies/{bundle}Read the effective policy bundleRoadmap

Related: JavaScript SDK and Python SDK (both Draft) will wrap these endpoints when they go live. Until then, run the quickstart locally.