Checkpoints

A checkpoint asks for approval of a single agent action. You create one before the action runs; Maetra evaluates it against your active policies and returns a decision - immediately for fast-path outcomes, or after a human responds.

Lifecycle#

create ─▶ evaluate ─┬─▶ approved / rejected / blocked   (terminal, signed)
                    └─▶ pending ─▶ (human decides) ─▶ approved / rejected
                                └─▶ (timeout)      ─▶ expired

Only approved decisions may continue to one-use execution authorization.

Create a checkpoint#

POST /v1/checkpoints — requires scope govern:checkpoints:write.

Evaluated synchronously: a fast-path policy may return a terminal decision in the same response; otherwise you get a pending checkpoint to poll.

Exact policies and decision intelligence

/v1/checkpoints uses the active policies configured in Govern. A policy can use exact saved conditions, or it can use AI agent decision intelligence to evaluate runtime risk.

You do not send a decision_intelligence flag on the checkpoint request. Enable decision intelligence on the policy in the dashboard. The API call stays the same; Maetra applies the policy mode and returns the same checkpoint decision shape.

Request body

curl -X POST "https://api.maetra.io/v1/checkpoints" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "delete_customer",
  "agent_name": "ops-agent",
  "payload": {
    "customer_id": "cus_41ab"
  },
  "reasoning": "GDPR erasure request #8821."
}'

With a registered agent

The call above uses agent_name because the agent isn't registered — the common case. If the agent is registered, pass its agent_id instead (or alongside agent_name) so the checkpoint is attributed to it:

{
  "action": "delete_customer",
  "agent_id": "agt_5Ab2",
  "payload": { "customer_id": "cus_41ab" },
  "reasoning": "GDPR erasure request #8821."
}

Policy scope with optional agent identity

agent_id is optional for /v1/checkpoints. When you send only agent_name, Govern still evaluates the action.

For automatic active-policy evaluation:

Use agent_id for stable attribution. Use agent_name for API-only or MCP agents that have not been registered yet. If you pass policy_ids or policy_group_ids, Maetra evaluates that explicit selection. The selection can include exact policies or decision-intelligence policies.

Response

{
  "checkpoint_id": "cp_7Yh2Qa",
  "agent_id": null,
  "agent_name": "ops-agent",
  "status": "pending",
  "reason": null,
  "decision_token": null,
  "expires_at": "2026-07-07T12:05:00.000Z",
  "evals": [
    { "policy_name": "Destructive actions", "status": "pending", "quorum_required": 2, "quorum_met": 0, "pool_size": 4 }
  ]
}

Eval object: policy_id, policy_name, applicability, status, quorum_required, quorum_met, pool_size.

Get a checkpoint (cold poll)#

GET /v1/checkpoints/{id} — scope govern:checkpoints:read. Returns the current state without waiting. Keep ≥1 second between polls of the same checkpoint; prefer the long-poll below.

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

Wait for a decision (long-poll)#

GET /v1/checkpoints/{id}/wait — scope govern:checkpoints:read. Holds the connection open until the checkpoint changes state or the hold elapses. The efficient way to wait for a human.

• Query timeout: hold seconds, 1–55 (default 50).
• 200 — changed; body is the new state. 202 — no change; reconnect.

curl "https://api.maetra.io/v1/checkpoints/cp_7Yh2Qa/wait?timeout=50" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Recommended flow#

1. POST /v1/checkpoints.
2. If status is already terminal, act on it (and verify the token).
3. If pending, long-poll /wait until terminal.
4. On approved, verify the decision token, then consume it through execution authorization immediately before acting. Record each attempt and verify the effect. On anything else, don't act.