Runtime API
One endpoint an agent calls to act, and exactly three shapes the response can take.
Every real-world action an agent wants to take is expressed as a signed Intent, submitted to a single endpoint. This page covers that endpoint directly; if you're using the Python SDK, agent.authorize(...) is this same call with signing handled for you -- see SDKs. For the product-level explanation of what this endpoint is evaluating against, see Runtime Authority.
POST /v1/intents
POST /v1/intents
X-PayReality-Key-Id: <certificate_id>
X-PayReality-Signature: <ed25519 signature over the raw request body>
Content-Type: application/json
{
"agent_id": "agt_8f2b1c",
"action": "vendor_payment",
"amount": 8500,
"currency": "USD",
"counterparty": "vendor_772",
"context": { "cost_center": "EMEA-04" },
"requested_at": "2026-08-03T09:14:02Z",
"nonce": "8f14e45f-ceea-4d21-8b5b-2f0e9c1a6f3a"
}nonce makes each request unique even if the same action is retried; the signature covers the entire raw body, so nothing in it can be altered in transit without invalidating the signature.
The three outcomes
Every Intent resolves to exactly one of three outcome values. There is no fourth path, and no partial success.
{
"decision_id": "dec_3a91f0",
"outcome": "ALLOW",
"reason": "within_delegated_authority",
"evidence_id": "ev_7c02d4",
"evaluated_at": "2026-08-03T09:14:02.118Z"
}{
"decision_id": "dec_3a91f1",
"outcome": "DENY",
"reason": "exceeds_approval_limit",
"evidence_id": "ev_7c02d5",
"evaluated_at": "2026-08-03T09:14:02.093Z"
}{
"decision_id": "dec_3a91f2",
"outcome": "HUMAN_REVIEW",
"reason": "requires_dual_approval",
"evidence_id": "ev_7c02d6",
"status": "PENDING",
"evaluated_at": "2026-08-03T09:14:02.077Z"
}reason is a stable, machine-readable code naming the specific policy or authority-graph condition that produced the outcome -- not a free-text explanation that can change wording between requests.
Decision lifecycle for Human Review
An ALLOW or DENY is terminal the moment it's returned. HUMAN_REVIEW is not: it comes back with status: "PENDING", and a human resolves it separately:
{
"decision_id": "dec_3a91f2",
"outcome": "HUMAN_REVIEW",
"status": "RESOLVED",
"resolution": {
"resolution": "approved",
"resolved_by": "j.matsimela@acme.example",
"resolved_at": "2026-08-03T09:47:11Z",
"reason": "Reviewed and approved."
}
}Poll GET /v1/decisions/{decision_id} until status flips from PENDING to RESOLVED, or use the webhook events covering this transition -- see Webhooks.
Request flow
The signature is verified first, before anything else runs: an Intent that doesn't verify is rejected with 401 and never reaches evaluation at all, so a forged or corrupted request never shows up as a real DENY decision.
Response flow
A successful evaluation is always 200 OK, whether the outcome is Allow, Deny, or Human Review -- the HTTP status describes whether the platform successfully evaluated the request, not whether the action was approved. A 4xx or 5xx means evaluation itself didn't complete; see API Reference for the full status code and error list.