Policies

Policies decide what happens when a checkpoint is created: whether they apply to an action, and how it's handled - auto-approve, auto-block, or route to approvers with a quorum and timeout.

Policies are authored in the dashboard. Over the API they are read-only — you list the active set so an agent (or your tooling) can see which controls apply.

Policy modes#

Govern supports two policy modes:

Mode	Use it for	Runtime behavior
Exact policy setup	Known action patterns like refunds, transfers, record changes, outbound messages, or data exports.	Maetra checks the saved policy conditions, then applies the configured approval, block, quorum, timeout, and notification settings.
Decision intelligence	Actions where risk depends on runtime context instead of one exact condition.	Maetra evaluates the checkpoint according to the policy settings and can allow, request approval, or block based on the selected mode.

Decision intelligence is enabled on the policy in the dashboard. API and MCP callers do not send a separate decision_intelligence field. They send the same checkpoint payload, and the active policy controls whether Maetra uses exact conditions or runtime decision intelligence.

List active policies#

GET /v1/policies/active — requires scope govern:policies:read.

curl "https://api.maetra.io/v1/policies/active" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Response

{
  "policies": [
    {
      "id": "pol_2Kd9",
      "name": "High-value transfers",
      "description": "Route transfers over $1,000 to finance.",
      "is_default": false,
      "autonomy_gate": "L3",
      "match_tree": { "all": [ { "field": "action", "eq": "transfer_funds" } ] },
      "on_match": "require_approval",
      "evaluation_mode": "exact_policy",
      "decision_intelligence_mode": null,
      "approver_mode": "any",
      "quorum_required": 1,
      "timeout_seconds": 300,
      "on_timeout": "reject",
      "notifications": { "email": true, "slack_channel": true, "slack_dm": false },
      "version": 4,
      "updated_at": "2026-07-01T09:12:00.000Z"
    }
  ]
}

Field	Type	Description
`id`	string	Policy ID. Pass to `policy_ids` on a checkpoint to scope evaluation.
`name` / `description`	string	Human-facing labels.
`is_default`	boolean	Whether it's a workspace default.
`autonomy_gate`	string	Autonomy level (`L0`–`L5`) at/above which it engages.
`match_tree`	object	Condition tree deciding whether it applies.
`on_match`	string	What to do when it applies (e.g. `require_approval`, `block`).
`evaluation_mode`	string	`exact_policy` or `decision_intelligence`.
`decision_intelligence_mode`	string \| null	Decision-intelligence mode when `evaluation_mode` is `decision_intelligence`.
`approver_mode`	string	How approvers are selected (e.g. `any`).
`quorum_required`	integer	Approvals needed to pass.
`timeout_seconds`	integer	How long to wait for the quorum.
`on_timeout`	string	What to do if the timeout elapses (e.g. `reject`).
`notifications`	object	`email`, `slack_channel`, `slack_dm` booleans.
`version`	integer	Increments on every edit.
`updated_at`	string	ISO 8601 timestamp.

Scoping a checkpoint to specific policies#

By default a checkpoint is evaluated against all applicable active policies. Disabled and deleted policies are not evaluated. Pass policy_ids (or policy_group_ids) to restrict evaluation to specific exact policies or decision-intelligence policies:

{ "action": "transfer_funds", "policy_ids": ["pol_2Kd9"] }