> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsentinel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies API

> Create policies, compile from prose, manage version history, rollback, and sync to SDKs.

## 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](#version-history) below.

## Compile from prose / YAML / JSON

```http theme={null}
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](/sdk/python/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

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

```json theme={null}
{
  "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

```http theme={null}
GET /api/v1/policies/{policy_id}/versions/{version_id}
```

### Review a version

```http theme={null}
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

```http theme={null}
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)

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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

* [SDK → Prose policies](/sdk/python/prose-policies) — natural-language authoring
* [Console → Settings](/console/settings) — version history + diff + rollback UI
* [Console → Replay](/console/replay) — simulate policies against past runs