Runtime API

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.

Capability Authorization

For a decision that needs stronger execution control than a Decision record alone provides, you can issue a short-lived, single-use Capability tied to that exact decision. It's a distinct step from evaluation itself: not every decision has one issued for it. PayReality issues and verifies the Capability; it doesn't consume it or call your enterprise system. audience (shown below as "reference-pep") names the customer-operated enforcement point that will actually verify and consume it, the trusted checkpoint that decides whether the downstream operation proceeds.

{
  "audience": "reference-pep",
  "issued_by": "j.matsimela@acme.example",
  "ttl_seconds": 300
}

// 200 OK
{
  "token": "<opaque signed capability token>",
  "capability_id": "cap_9a71e0",
  "expires_at": "2026-08-03T09:19:02.118Z"
}

For a decision that resolved to HUMAN_REVIEW and was since approved, use POST /v1/decisions/{decision_id}/capability-token/from-review instead: the same request and response shape, gated on the approval rather than a direct Allow. The original decision is never rewritten to Allow; it keeps reading Human Review, permanently. Either endpoint can issue at most one Capability per decision, ever, and only for one that hasn't already expired unconsumed or been consumed.

{
  "token": "<the issued token>",
  "audience": "reference-pep",
  "action": "supplier_bank_details_change",
  "resource": "supplier:SUPPLIER_482",
  "constraints": {},
  "environment": "production"
}

// 200 OK
{
  "capability_id": "cap_9a71e0",
  "decision_id": "dec_3a91f2",
  "resource": "supplier:SUPPLIER_482",
  "constraints": {}
}

Verification requires authenticating as a specific organization (a bearer token, or the shared operator credential naming its target organization explicitly, see Authentication) holding the CAPABILITY_VERIFY permission: a caller acting for one organization cannot consume a Capability belonging to another. Immediately before consuming it, the platform also rechecks that the originating Agent, the Organization, and any Trusted Integration identity and Runtime Connection the Capability depends on are still active, and fails closed if one isn't. Consuming a Capability is single-use: presenting the same token again is rejected, whether that's a genuine replay or a second concurrent attempt.

Execution receipts and reconciliation EARLY ACCESS

PayReality records what it authorized. When a separately authenticated destination or trusted execution adapter later supplies an execution receipt for a decision, PayReality verifies that receipt's linkage back to the original decision and reconciles the reported execution against the action it actually authorized. This is a newer surface than the rest of this page, and not yet part of the stable public contract documented in API Reference; treat the shape below as illustrative rather than a guaranteed wire format.

Reconciliation resolves to exactly one outcome:

MATCHED           # the reported execution matches what was authorized
MISMATCHED        # the reported execution differs from what was authorized
EXECUTION_FAILED  # the destination reported the action did not execute
PARTIAL           # only part of the authorized action was reported executed
RECEIPT_MISSING   # no execution receipt has been reported yet
INDETERMINATE     # the receipt could not be reconciled with confidence

{
  "decision_id": "dec_3a91f0",
  "outcome": "ALLOW",
  "evidence_id": "ev_7c02d4",
  "reconciliation": {
    "status": "MATCHED",
    "receipt_id": "exec_rcpt_9a1f...",
    "reported_by": "trusted-execution-adapter",
    "reconciled_at": "2026-08-03T09:16:41.203Z"
  }
}

A cryptographically authenticated execution receipt proves what the trusted source reported. It does not independently prove that the underlying business system or real-world event was truthful: PayReality authenticates the receipt's origin and reconciles its content against the authorized action, it doesn't independently confirm the real-world outcome. See Authorization Receipts and Evidence Verification for how this fits into the wider evidence record, and Webhooks for the planned notification for a reconciliation completing.