Skip to main content

​
CRUD endpoints

  • POST /api/v1/policies/
  • GET /api/v1/policies/
  • GET /api/v1/policies/{policy_id}
  • PUT /api/v1/policies/{policy_id}
  • DELETE /api/v1/policies/{policy_id}
Policy fields include:
  • Budgets: run_budget, session_budget, action_budgets
  • Lists: denied_actions, allowed_actions
  • Rate limits: rate_limits
  • Scope: scope (global / agent / run / group / mission) and target_id
  • Approvals: require_approval, approval_actions, approval_tags, approval_risk_levels, approval_threshold_usd, approval_timeout_seconds, default_approvers, approval_rules
  • Evidence graph: evidence_requirements, evidence_max_age_seconds, commit_actions, evidence_actions
  • Argument constraints: argument_constraints (per-action JSON Schema), grounding_rules (field-level)
Every successful PUT creates a PolicyVersion snapshot — see Version history below.

​
Compile from prose / YAML / JSON

POST /api/v1/policies/compile
Content-Type: application/json

{ "source": "...", "source_format": "prose" | "yaml" | "yml" | "json" | "markdown" | "md" }
Stateless adapter: returns a validated PolicyCreate-shaped dict (or structured errors). Prose and Markdown are routed through Gemini (gemini-2.5-flash); YAML/JSON skip the LLM and validate directly. Full reference: SDK → Prose policies.

​
Version history

Every PUT /api/v1/policies/{policy_id} creates an immutable PolicyVersion snapshot with status active, archives the previous active version, and updates policy.current_version_id.

​
List versions

GET /api/v1/policies/{policy_id}/versions?skip=0&limit=50

{
  "data": [
    {
      "id": "v_…",
      "policy_id": "p_…",
      "version_number": 7,
      "status": "active",
      "policy_data": { /* full snapshot */ },
      "change_summary": "Updated: denied_actions, approval_threshold_usd",
      "author_id": "usr_abc",
      "reviewer_id": "usr_abc",
      "reviewed_at": "2026-04-18T16:45:00Z",
      "created_at": "2026-04-18T16:45:00Z"
    }
  ],
  "count": 7
}
Status values: draft, in_review, active, archived.

​
Get a version

GET /api/v1/policies/{policy_id}/versions/{version_id}

​
Review a version

POST /api/v1/policies/{policy_id}/versions/{version_id}/review
Marks a draft or in_review version as reviewed by the caller.

​
Rollback to a version

POST /api/v1/policies/{policy_id}/rollback/{version_id}
Copies policy_data from the chosen version back onto the policy, archives the current active version, and creates a new active PolicyVersion snapshot. The rollback is itself a versioned event in the history.

​
Policy exceptions

Time-bound or count-bound carve-outs that let specific agents/runs bypass a policy:
  • GET /api/v1/policies/{policy_id}/exceptions
  • POST /api/v1/policies/{policy_id}/exceptions
  • DELETE /api/v1/policies/{policy_id}/exceptions/{exception_id}

​
Policy sync (SDK)

GET /api/v1/policies/sync?agent_id=...&run_id=...
Returns enabled policies for the current user. The SDK merges them in scope order (global → agent → run) and applies the most restrictive setting per field.

​
Test alert

POST /api/v1/policies/{policy_id}/test-alert
Sends a sample alert email to the policy’s default_approvers to verify the channel works.

​
Simulate

POST /api/v1/policies/{policy_id}/simulate
Replays historical actions against the current policy and reports which would have been blocked, escalated, or allowed. Used by the console’s policy preview.

​
See also