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

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

Status values: draft, in_review, active, archived.

​
Get a version

​
Review a version

Marks a draft or in_review version as reviewed by the caller.

​
Rollback to a version

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)

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

Sends a sample alert email to the policy’s default_approvers to verify the channel works.

​
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