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 two rows marked "Early Access" in their description are 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.
| POST | /v1/agents | Register a new agent identity. |
| POST | /v1/agents/{id}/activate | Activate a registered agent. |
| POST | /v1/agents/{id}/rotate-keys | 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/decisions/{id}/execution-receipt | Early Access: submit an authenticated execution receipt for reconciliation against the authorized action. |
| GET | /v1/decisions/{id}/reconciliation | Early Access: retrieve the reconciliation outcome (MATCHED, MISMATCHED, EXECUTION_FAILED, PARTIAL, RECEIPT_MISSING, or INDETERMINATE) for a decision. |
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
{
"error": {
"code": "invalid_signature",
"message": "Signature verification failed for the provided key_id."
}
}error.code is stable and intended to be matched on in code; error.message is for humans and may change wording between releases.
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.