API Reference
The endpoint map, request conventions, and error model. For the live, always-current version of this reference, see the link at the bottom.
Endpoints
The row marked "Early Access" in its description is newer than the rest of this list and not yet part of the stable public contract; see Runtime API for what that currently means in practice. Reconciliation itself (comparing a reported execution against what was authorized) is real and computed internally today, but it has no API endpoint of its own yet: nothing below currently returns a reconciliation result. See the Order Walkthrough's step 8 for what the receipt path does and doesn't establish in the meantime.
| POST | /v1/agents | Register a new agent identity. |
| POST | /v1/agents/{id}/activate | Activate a registered agent. |
| POST | /v1/agents/{id}/rotate | Rotate an agent's signing certificate. |
| POST | /v1/agents/{id}/retire | Permanently retire an agent. |
| POST | /v1/intents | Submit a signed Intent for evaluation. |
| GET | /v1/decisions/{id} | Retrieve a decision, including Human Review resolution once resolved. |
| GET | /v1/decisions/{id}/receipt | Retrieve the signed Authorization Receipt for a decision. |
| POST | /v1/decisions/{id}/resolve | Resolve a decision pending Human Review. |
| POST | /v1/decisions/{id}/capability-token | Issue a Capability Authorization for an Allow decision. |
| POST | /v1/decisions/{id}/capability-token/from-review | Issue a Capability Authorization for an approved Human Review decision. |
| POST | /v1/capability-tokens/verify | Verify and consume a Capability Authorization, organization-scoped. |
| GET | /v1/evidence | List evidence records. |
| POST | /v1/evidence/{id}/verify | Verify an evidence record's signature. |
| GET | /v1/principals | List principals in the Authority Graph. |
| POST | /v1/execution-receipts | Early Access: submit an authenticated execution receipt (decision_id in the body) for reconciliation against the authorized action. Authenticated as a Trusted Adapter identity, not a bearer token or API key. |
Headers
Every request needs exactly one of the four credentials covered in Authentication:
X-PayReality-Operator-Key: <operator_key>
Authorization: Bearer <session_token_or_api_key>
X-PayReality-Key-Id: <certificate_id> # + X-PayReality-Signature, for agent-signed callsSchemas
Request and response bodies are JSON. The Intent, Decision, Agent, and Evidence shapes are covered with full examples on their own pages: Runtime API, Agent Registration, and Evidence Verification.
Status codes
| Code | Meaning |
|---|---|
| 200 | Request succeeded. For /v1/intents, this includes Deny and Human Review: the platform successfully evaluated the request. |
| 401 | Missing, invalid, or unverifiable signature/credential. |
| 403 | Authenticated, but the credential's role lacks the required permission. |
| 404 | The referenced resource (agent, decision, evidence record) doesn't exist. |
| 422 | The request body failed validation before evaluation was attempted. |
| 429 | Rate limited. |
| 5xx | The platform failed to complete evaluation. Safe to retry with backoff. |
Errors
{
"detail": "invalid_signature"
}Every error response is FastAPI's own default shape: a flat, stable, snake_case detail string, matched on in code (e.g. capability_constraint_mismatch, agent_not_operational). There is no separate, richer code/message envelope beyond this.
Pagination
List endpoints (/v1/evidence, /v1/principals) accept limit and offset query parameters; responses include a total count alongside the page of results.
Versioning
The /v1 prefix is the API version. A breaking change ships as /v2, not a silent change to /v1: existing integrations are never broken by a new version shipping alongside them.
For the live, interactive, always-current reference generated directly from the running platform, see https://api.aisecurewatch.com/docs.