> For the complete documentation index, see [llms.txt](https://docs.brain.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.brain.fi/api-reference/policy-api.md). # Policy API Compose a policy, sign it, activate it, evaluate proposed actions against it, and lint or simulate before signing. Every Policy route is tenant-scoped: the `{tenant_id}` (UUID) appears in the path, and your token's tenant must match. | Operation | Endpoint | | -------------------------- | ------------------------------------------------- | | Get the active policy | `GET /v1/policy/{tenant_id}` | | Compose a candidate policy | `POST /v1/policy/{tenant_id}/compose` | | Sign + activate | `POST /v1/policy/{tenant_id}/sign` | | List versions | `GET /v1/policy/{tenant_id}/versions` | | Evaluate an action | `POST /v1/policy/{tenant_id}/evaluate` | | Lint a draft | `POST /v1/policy/{tenant_id}/lint` | | Simulate against a version | `POST /v1/policy/{tenant_id}/simulate` | | Replay a period | `POST /v1/policy/{tenant_id}/simulate-historical` | | Diff two versions | `POST /v1/policy/{tenant_id}/diff` | There is no separate `register` or `revoke` endpoint. Activation happens at `sign`, and superseding a version means signing a new one. The previous active version is recorded in `versions` history. ### Compose a Candidate Policy The DSL is structured JSON, not prose. The compose route validates it and returns the canonical hash plus the EIP-712 typed-data payload the tenant signers will sign. ```http POST /v1/policy/{tenant_id}/compose Authorization: Bearer Content-Type: application/json { "content": { "version": 5, "rules": [ { "id": "rule_invoice_under_5k", "applies_to": ["outbound_payment"], "when": { "amount.lte": { "currency": "USD", "value": "5000" }, "counterparty.in": "vendors.trusted" }, "execute": "auto" }, { "id": "rule_invoice_above_5k", "applies_to": ["outbound_payment"], "when": { "amount.gt": { "currency": "USD", "value": "5000" } }, "require": "cfo_approval", "execute": "confirm" } ], "lists": { "vendors.trusted": ["cp_aws", "cp_gcp"] } } } ``` The `content` wrapper and the numeric `version` are mandatory. An optional top-level `quorum_required` sets how many distinct authorized signers `sign` needs (default `1`). Response: ```json { "policy_id": "pol_8231", "state": "pending_signatures", "signing_payload": { "domain": {...}, "types": {...}, "message": {...} } } ``` `execute` is one of `auto | confirm | reject`. These are the rule-level outcomes that produce the policy decision (`allow | confirm | reject`). ### Sign and Activate Each required signer signs the `signing_payload` from `compose`, then someone (any caller with `policy:sign`) submits the `policy_id` and all signatures together: ```http POST /v1/policy/{tenant_id}/sign Authorization: Bearer Content-Type: application/json { "policy_id": "pol_8231", "signatures": [ { "address": "0xCFO...", "signature": "0x..." }, { "address": "0xCTO...", "signature": "0x..." } ] } ``` `200 OK` with the serialized policy, an `activated` flag, and any activation `warnings`: ```json { "policy": { "id": "pol_8231", "version": 4, "state": "active", "content": { "version": 4, "rules": [...] }, "content_hash": "abc123...", "signers": [...], "quorum_required": 2, "activated_at": "2026-05-28T12:00:00Z", "deactivated_at": null, "created_by": "usr_...", "created_at": "2026-05-28T11:59:00Z" }, "activated": true, "warnings": [] } ``` The signature count reaching `quorum_required` flips the policy to `active` (`activated: true`). Below quorum, the signatures are recorded and the policy stays `pending_signatures`. A signature that fails to verify, a duplicate signer, or a signer that is not an authorized tenant signer returns `401` with `policy_signature_invalid`. Signing a policy that is not awaiting signatures returns `409` with `policy_quorum_not_met`. ### Get the Active Policy ```http GET /v1/policy/{tenant_id} Authorization: Bearer ``` Returns the currently active `Policy` for the tenant (`404` if none has been activated). For a specific historical version, use `/versions`. ### List Versions ```http GET /v1/policy/{tenant_id}/versions Authorization: Bearer ``` ```json { "versions": [ { "id": "pol_8231", "version": 4, "content_hash": "0xabc...", "activated_at": "2026-05-28T...", "deactivated_at": null }, { "id": "pol_5417", "version": 3, "content_hash": "0x111...", "activated_at": "2026-03-01T...", "deactivated_at": "2026-05-28T..." } ] } ``` ### Evaluate an Action Evaluate an action against the active policy. This endpoint does not propose or reserve a payment, but every call emits a `policy.evaluate` audit event. The endpoint uses the same policy VM as the section 6 gate, but it is not a complete gate simulation. Its request parser accepts only `kind`, `counterparty_id`, `amount`, `agent_role`, and `timestamp`. It does not accept or populate `agent_id`, `tenant_category`, `confidence`, `evidence_score`, `risk_level`, `spend_in_window`, `tx_count_in_window`, `behavior_hash`, or `action_id`. Rules using those inputs can therefore evaluate differently here than they do with a fully populated gate action. ```http POST /v1/policy/{tenant_id}/evaluate Authorization: Bearer Content-Type: application/json { "action": { "kind": "outbound_payment", "counterparty_id": "cp_aws", "amount": { "currency": "USD", "value": "7800" } } } ``` ```json { "outcome": "confirm", "matched_rule_id": "rule_invoice_above_5k", "required_approvers": ["cfo"], "trace": [ { "rule_id": "rule_invoice_under_5k", "matched": false, "checks": [{ "key": "amount.lte", "passed": false, "detail": "USD 5000" }] }, { "rule_id": "rule_invoice_above_5k", "matched": true, "checks": [{ "key": "amount.gt", "passed": true, "detail": "USD 5000" }] } ] } ``` ### Three Possible Decisions | Decision | Meaning | | --------- | ------------------------------------------------------------------------------------- | | `allow` | Rule matched with `execute: "auto"`; action can proceed straight to the ยง6 gate | | `confirm` | Rule matched with `execute: "confirm"`; named `required_approvers` must sign first | | `reject` | Rule matched with `execute: "reject"`, or no rule matched the default-deny vocabulary | Casing is **lowercase**. `allow | confirm | reject`. The historical-simulation counters mirror it (`would_allow`, `would_confirm`, `would_reject`). #### Unmatched high-risk agent actions The policy VM remains deny-by-default. A normal unmatched rule evaluation still returns `reject`, and low-stakes or money-path proposal types keep their existing fail-closed behavior. There is one compatibility wrapper for reviewable high-risk non-money proposals: `PolicyService.evaluateLegacy` converts unmatched `agent_action` fallthroughs for `collections`, `fraud_anomaly`, and `vendor_risk` to `confirm` with `required_approvers: ["signer"]`. The same fallback also applies to stored high-risk action types such as `flag_transaction`, `block_payment`, `flag_vendor_risk`, `freeze_card`, `create_dispute_draft`, `require_approval`, and `escalate`. This keeps suspicious transactions, vendor-risk holds, and collections follow-ups visible for human review instead of silently closing them as policy rejections. `payment` proposals are deliberately not included in this fallback. #### Decision vocabulary across surfaces `allow | confirm | reject` is the canonical protocol decision. The rule-level `execute` field and the SDK use aliases that map 1:1; the PaymentIntent status reflects the same outcome: | Protocol decision (HTTP/MCP) | Rule-level `execute` | SDK `decision.outcome` / `action.status` | Resulting PaymentIntent status | | ---------------------------- | -------------------- | ---------------------------------------- | ---------------------------------- | | `allow` | `auto` | `auto` | `approved` or `pending_approval`\* | | `confirm` | `confirm` | `needs_approval` | `pending_approval` | | `reject` | `reject` | `rejected` | `rejected` | Compare against `allow | confirm | reject` over HTTP/MCP; the `auto | needs_approval | rejected` triple is an SDK alias, not the protocol vocabulary. \* An allow decision still enters `pending_approval` when the hard human-approval floor applies. The floor always applies to `onchain_transfer` and `escrow_release`, applies to `wire` while the fiat floor is enabled, and applies to `ach_outbound`, `ach_inbound`, `card_payment`, and `x402_settle` unless the matched rule carries a covering signed autonomous amount cap. ### Action Vocabulary The evaluate `action.kind` is one of the following. There is no `rail` field on the evaluate action. | `kind` | Domain | | ------------------ | ------------------------------------------------- | | `outbound_payment` | Money leaving (ACH, wire, on-chain, x402, escrow) | | `inbound_payment` | Money arriving | | `ledger_write` | A Ledger-row mutation (e.g. agent normalization) | | `onchain_tx` | A non-payment on-chain transaction | | `agent_action` | A non-money agent action gated by policy | | `any` | Only valid inside a rule's `applies_to` catch-all | A rule's `applies_to` accepts the same `kind` values, including `any`. (The PaymentIntent layer uses a separate, broader `action_type` set. `ach_outbound`, `wire`, `x402_settle`, etc.. Those map onto the `kind` values internally.) Proposal read APIs expose a separate public proposal `type`. Stored agent `action_type` values are preserved as `stored_action_type` and then mapped to a public proposal type through the proposal read model. For example, `flag_transaction` maps to `fraud_anomaly`, `block_payment` maps to `vendor_risk`, and `propose_match` maps to `reconciliation`. Ambiguous stored actions such as `notify`, `escalate`, `create_task`, and `recommend_action` use the agent role or kind instead of action-name guessing. ### Lint a Draft Before composing, run a linter against a policy-content blob to catch shape / semantic problems: ```http POST /v1/policy/{tenant_id}/lint Authorization: Bearer Content-Type: application/json { "policy_content": { "rules": [...] } } ``` ```json { "tenant_id": "acme", "errors": 0, "warnings": 2, "findings": [ { "code": "rule_amount_currency_missing", "severity": "WARN", "rule_id": "rule_3", "message": "amount.gt without explicit currency" } ] } ``` ### Simulate Against a Version Replay a single action against a specific historical policy version: ```http POST /v1/policy/{tenant_id}/simulate Authorization: Bearer Content-Type: application/json { "action": { "kind": "outbound_payment", "counterparty_id": "cp_aws", "amount": { "currency": "USD", "value": "7800" } }, "version": 3 } ``` Returns `{ "decision": , "policy_version": 3 }`. Unlike `/evaluate`, simulate wraps the decision with the `policy_version` it replayed against. ### Replay a Period Replay every action in a time window against a candidate (unsigned) policy. Useful for asking "would version 5 have changed anything?": ```http POST /v1/policy/{tenant_id}/simulate-historical Authorization: Bearer Content-Type: application/json { "policy_content": { "rules": [...] }, "period_start": "2026-01-01", "period_end": "2026-04-30" } ``` ```json { "total": 4127, "would_allow": 3902, "would_confirm": 201, "would_reject": 24, "diff_vs_active": { "newly_allowed": ["pi_001"], "newly_rejected": ["pi_002"], "changed_other": ["pi_003"], "unchanged": 4124 } } ``` ### Diff Two Versions ```http POST /v1/policy/{tenant_id}/diff Authorization: Bearer Content-Type: application/json { "from_version": 3, "to_version": 4 } ``` ```json { "from_version": 3, "to_version": 4, "added": ["rule_x402_micropayment_cap"], "removed": [], "modified": [ { "rule_id": "rule_invoice_above_5k", "field": "require", "before": null, "after": "cfo_approval" } ] } ``` ### What's Next
๐Ÿ“‹ Policy and PermissioningThe conceptual model.Policy and Permissioning
๐Ÿ“œ BrainPolicyRegistryThe on-chain registry.BrainPolicyRegistry
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.brain.fi/api-reference/policy-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.