DEVELOPERS

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

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.
POST	/v1/decisions/{id}/resolve	Resolve a decision pending Human Review.
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.

Headers

Every request needs exactly one of the four credentials covered in Authentication:

one of

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 calls

Schemas

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 response shape

{
  "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.

Other documentation

Getting StartedCreate an organization, register an agent, and get your first Authorization Receipt back.ArchitectureThe full path from an agent's signed intent to a decision and its evidence, component by component.Runtime APIThe Intent API: POST /v1/intents, its three possible outcomes, and the request/response lifecycle.AuthenticationThe Operator Key, per-user roles and permissions, per-developer API keys, and agent certificates.Authority GraphDelegated authority, roles, resources, and approval limits, and how governance becomes machine-readable.Runtime PoliciesHow a policy is compiled, versioned, and deployed, and why that differs from the governance document it came from.Authorization ReceiptsWhy logs aren't enough, the receipt lifecycle, and the planned architecture for independent verification.Evidence VerificationSignature verification, evidence export, and audit workflows against the Evidence Portal today.SDKsThe Python SDK, and the language roadmap for Node.js, Go, Java, .NET, and Rust.WebhooksEnterprise events -- IntentReceived, DecisionCompleted, ReceiptIssued, and more -- with real payloads.Integration ExamplesRotating keys, sending a heartbeat, and retiring an agent, with real SDK code for each.Integration GuidesConnecting Runtime Authority to agent frameworks, model providers, and enterprise systems.Agent RegistrationThe full agent lifecycle: registered, active, suspended, retired, or revoked.