API reference

List the purchases you submitted#

GET/v1/purchase-requests

API key bound to an agentOAuth: purchase:read

The purchases the calling credential submitted, newest first.

Scoped to the credential, exactly as reading one purchase is. A key that replaced another does not see the earlier key's purchases; subscribe to webhooks for a record that survives rotation.

Credential: An API key bound to an agent. OAuth connections need `purchase:read`.

Rate limit: 600 per minute per credential.

Parameters

Responses

Submit a purchase for a decision#

POST/v1/purchase-requests

API key bound to an agentOAuth: purchase:request

Asks the Trust Engine whether this agent may make this purchase, and records the answer.

All three outcomes — `APPROVED`, `REJECTED` and `REQUIRES_APPROVAL` — are successful calls. Branch on `decision.outcome`, never on the HTTP status code: the status describes whether the question could be answered, and a refusal is an answer.

`REQUIRES_APPROVAL` means a person has been asked and the budget is held until `approval.expiresAt`. Poll `GET /v1/purchase-requests/{purchaseRequestId}` for what they decided.

An `APPROVED` purchase carries a purchase authorization: an id to hand to whatever will make the purchase, and the time until which it can be used. Veriticity authorizes a purchase; it does not make one.

Requires an API key bound to an agent, or an OAuth connection granted `purchase:request`. An organization-scoped key names no identity to attribute a purchase to and is refused.

Credential: An API key bound to an agent. OAuth connections need `purchase:request`.

Rate limit: 120 per minute per credential; 600 per minute per organization.

Request body: at most 65536 bytes, or 655360 bytes when it states `items`.

Parameters

Request body

Responses

Read back a purchase you submitted#

GET/v1/purchase-requests/{purchaseRequestId}

API key bound to an agentOAuth: purchase:read

What happened to a purchase, including the decision in force and the approval if one was opened. This is how you find out what a person decided after a `REQUIRES_APPROVAL`.

A purchase is readable by the credential that submitted it and by nothing else. Another agent's, another connection's, another tenant's and a malformed id are all the same 404.

Reads nothing into the audit trail and re-evaluates nothing.

Credential: An API key bound to an agent. OAuth connections need `purchase:read`.

Rate limit: 600 per minute per credential.

Parameters

Responses

Cancel a purchase that is waiting for approval#

POST/v1/purchase-requests/{purchaseRequestId}/cancel

API key of either kindOAuth: purchase:request

Takes back a request nobody has approved yet. The approval is no longer asked for, the budget it was holding is released, and the purchase becomes `CANCELLED`.

Only a request still waiting for approval can be cancelled. Anything else is refused with `purchase_authorization_conflict`. An approved purchase is ended by withdrawing its authorization, which an agent's credential cannot do.

The credential that submitted the request may cancel it, and so may an organization-scoped key. Another credential's request is a 404.

Credential: An API key of either kind. OAuth connections need `purchase:request`.

Rate limit: 120 per minute per credential.

Request body: at most 16384 bytes.

Parameters

Request body (optional)

Responses

Report what became of an approved purchase#

POST/v1/purchase-requests/{purchaseRequestId}/outcome

API key of either kindOAuth: purchase:request

Says what happened to a purchase this credential submitted and that was authorized: `COMPLETED` for `finalAmountMinor`, `COMPLETED_AMOUNT_UNKNOWN`, `PARTIAL` for the items in `itemPositions`, `FAILED`, or `REFUNDED` by `refundMinor`.

A report is the agent's word. It is recorded as reported by the assistant, never as verified. Under the organisation's default policy it is shown and changes nothing until a person confirms what was charged; an organisation that trusts assistant reports accepts it. It never approves a purchase or revives an authorization, and it makes, changes or cancels no order or payment.

An amount above what was approved is recorded and flagged for review. A final for each variable charge may be sent in `variableFinal`; `finalAmountMinor` is then the known amount plus every final.

Send a `reportId` with each report. The same report again returns `replayed: true` and records nothing; a different report under a used `reportId` is `report_id_reuse`. A later report with a new `reportId` replaces this credential's earlier one; a refund adds to it.

Only the credential that submitted the purchase may report on it. Anything else, including an organization-scoped key, is a 404. A purchase that was never authorized is `purchase_outcome_conflict`, and so is `REFUNDED` while the authorization can still be used: report a refund once it has been used or withdrawn.

Credential: An API key of either kind. OAuth connections need `purchase:request`.

Rate limit: 60 per minute per credential; 300 per minute per organization.

Request body: at most 16384 bytes.

Parameters

Request body

Responses

List purchase authorizations#

GET/v1/purchase-authorizations

Organisation-scoped API keyNo OAuth caller admitted

Your organization's purchase authorizations, newest first.

Filter with `status`. `status=expired` is the one to act on: authorizations that were never used and have expired. An expiry releases nothing, so each of their purchases still counts towards your budgets until you withdraw it.

No entry carries the purchase's terms.

Requires an organization-scoped API key.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 600 per minute per credential.

Parameters

Responses

Read the state of a purchase authorization#

GET/v1/purchase-authorizations/{authorizationId}

Organisation-scoped API keyNo OAuth caller admitted

Whether a purchase authorization is active, used, expired, withdrawn or voided, and whether it can be used right now.

It returns none of the purchase's terms. An authorization from another organization and a malformed id are the same 404.

Requires an organization-scoped API key. An agent reads the authorization of its own purchase on the purchase.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 600 per minute per credential.

Parameters

Responses

Get an execution token for your own purchase authorization#

POST/v1/purchase-authorizations/{authorizationId}/execution-token

API key bound to an agentNo OAuth caller admitted

Issues the token an agent's key sends to use one purchase authorization. Only the key that submitted the purchase can ask, and only while the authorization is `active`.

The token is shown once and works for this authorization only. It has no lifetime of its own: it stops working when the authorization is used, withdrawn, voided or expires, whichever is first, and when another token is issued for it. It does not change the authorization's terms or its expiry, and grants nothing else.

Asking again issues a new token and the earlier one stops working, so a lost response is recovered by asking again. A used authorization gets no new token: to retry a use whose response was lost, send the same token, reference and terms again.

Requires an API key bound to an agent. An organization-scoped key uses authorizations without a token, and no OAuth connection can ask.

Credential: An API key bound to an agent. No OAuth scope reaches this operation.

Rate limit: 120 per minute per credential; 600 per minute per organization.

Parameters

Responses

Use a purchase authorization#

POST/v1/purchase-authorizations/{authorizationId}/use

API key of either kindNo OAuth caller admitted

Say what you are about to do, and learn whether the authorization covers exactly that. A match uses it, in the same step, and it cannot be used again.

`authorized` means the purchase authorization was verified and consumed. It does not mean a purchase was made. Veriticity does not execute the purchase and is not told its outcome.

A refusal is an answer, so it is a 200: branch on `result`, never on the HTTP status code, and do not proceed unless it is `authorized`. A refusal changes nothing: the authorization is exactly as it was, whatever was presented and however many times.

Terms are compared exactly. The amount must be the authorized amount to the minor unit, and every identifier the purchase stated must be presented and must match. `merchant` is compared with what was submitted; it is never looked up again. You are not told which term failed.

`executionReference` is your own identifier for this execution. Repeating a successful call with the same reference and the same terms returns the original answer with `replayed: true`.

Takes an API key of either kind. An agent's key uses only its own agent's authorization, and must send the execution token issued for it in `Veriticity-Execution-Token`: see `POST /v1/purchase-authorizations/{authorizationId}/execution-token`. Another agent's authorization is the same 404 as an unknown one. The organization's own key sends no token. No OAuth connection can use an authorization.

An authorization is used in Live only while the organization has a plan that includes purchase requests. Once its trial has ended, or with no plan, a use is refused with `plan_required` until an owner chooses one.

Credential: An API key of either kind. No OAuth scope reaches this operation.

Rate limit: 120 per minute per credential; 600 per minute per organization.

Request body: at most 16384 bytes, or 655360 bytes when it states `items`.

Parameters

Request body

Responses

Void a used purchase authorization#

POST/v1/purchase-authorizations/{authorizationId}/void

Organisation-scoped API keyNo OAuth caller admitted

Says an authorization was used and the purchase did not complete. Its purchase becomes `CANCELLED` and stops counting towards budgets. This can't be undone.

Works only on a `used` authorization. An unused one is refused with `purchase_authorization_conflict`: withdraw it instead.

Voiding is not a refund or a reversal. Veriticity moves no money and tells no payment system anything. It records what you say happened.

Repeating the call returns the same authorization with `replayed: true` and changes nothing.

Requires an organization-scoped API key.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 120 per minute per credential.

Request body: at most 16384 bytes.

Parameters

Request body

Responses

Withdraw an unused purchase authorization#

POST/v1/purchase-authorizations/{authorizationId}/withdraw

API key of either kindOAuth: purchase:request

Says an authorization that has not been used will not be. It can't be used afterwards, its purchase becomes `CANCELLED`, and the purchase stops counting towards budgets. This can't be undone.

Works on an `active` or an `expired` authorization. A `used` one is refused with `purchase_authorization_conflict`: void it instead.

Withdrawing is the only way an unused approval stops counting. An expiry does not release it.

Repeating the call returns the same authorization with `replayed: true` and changes nothing.

An organization-scoped key may withdraw any authorization. The credential that submitted a purchase may withdraw its authorization while it is unused, giving up authority it no longer needs; another credential's is a 404.

Credential: An API key of either kind. OAuth connections need `purchase:request`.

Rate limit: 120 per minute per credential.

Request body: at most 16384 bytes.

Parameters

Request body

Responses

Ask what would happen right now#

POST/v1/simulations/current-policies

API key of either kindOAuth: purchase:check

Runs the same evaluation `POST /v1/purchase-requests` would run, against the policies currently in force, and changes nothing: no purchase request, no decision, no budget reservation, no audit evidence, and no budget consumed.

This is how an agent finds out what it may spend before committing to asking.

Both API-key kinds reach it, and they behave differently: - an organization-scoped key must send `agentId` - an agent-bound key must not, and simulates as itself - an OAuth connection must not, and simulates as its agent

Credential: An API key of either kind. OAuth connections need `purchase:check`.

Rate limit: 120 per minute per credential.

Request body: at most 65536 bytes, or 655360 bytes when it states `items`.

Request body

Responses

Ask what a draft policy version would decide#

POST/v1/simulations/draft-policy

Organisation-scoped API keyNo OAuth caller admitted

Evaluates a purchase against one `DRAFT` policy version as it is currently written — the question you ask before activating it.

Organization-scoped API keys only. An agent may not read or simulate the guardrails being drafted for it, and no OAuth scope reaches this.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 120 per minute per credential.

Request body: at most 65536 bytes, or 655360 bytes when it states `items`.

Request body

Responses

Ask what a specific policy version would decide#

POST/v1/simulations/policy-version

Organisation-scoped API keyNo OAuth caller admitted

Evaluates a purchase against one `ACTIVE` or `ARCHIVED` policy version exactly as it was frozen — the question you ask about a decision that was already made, or about a version you are thinking of reinstating.

Organization-scoped API keys only.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 120 per minute per credential.

Request body: at most 65536 bytes, or 655360 bytes when it states `items`.

Request body

Responses

List spending policies#

GET/v1/policies

Organisation-scoped API keyNo OAuth caller admitted

Your organisation's spending policies, newest first.

Organization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 600 per minute per credential.

Parameters

Responses

Read one policy#

GET/v1/policies/{policyId}

Organisation-scoped API keyNo OAuth caller admitted

One policy with its version history and the agents it governs.

Organization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 600 per minute per credential.

Parameters

Responses

Read one policy version#

GET/v1/policies/{policyId}/versions/{versionId}

Organisation-scoped API keyNo OAuth caller admitted

A policy version in full, exactly as the Trust Engine reads it: what it is about, its rules, the conditions they name and its value sets.

Organization-scoped API keys only. An agent may not read the policies it is judged against — it learns what it may spend by asking `POST /v1/simulations/current-policies` instead. No OAuth scope reaches this.

Credential: An organization-scoped API key. No OAuth scope reaches this operation.

Rate limit: 600 per minute per credential.

Parameters

Responses