---
title: "Policy API"
description: "Author, version, simulate, test, activate and roll back policy."
label: "Policy"
generated: "the API catalogue in apps/control-plane/src/routes/developer.ts"
---


Policies are versioned and immutable once activated. Activation requires step-up authentication, a recorded reason, and passing test cases. Simulation has no side effects of any kind — no execution, no credential lease, no audit of a decision that did not happen.

:::warning Step-up required
2 endpoints in this group require a fresh step-up authentication within the last few minutes, even for a session that already holds the permission. They are marked below.
:::

## Endpoints

| | Endpoint | Permission | Notes |
| --- | --- | --- | --- |
| `GET` | `/v1/policies` | `policy:read` | — |
| `POST` | `/v1/policies` | `policy:create` | accepts `Idempotency-Key` |
| `GET` | `/v1/policies/builder-schema` | `policy:read` | — |
| `PATCH` | `/v1/policies/{policyId}` | `policy:update` | — |
| `POST` | `/v1/policies/{policyId}/activate` | `policy:activate` | step-up, high impact |
| `POST` | `/v1/policies/{policyId}/rollback` | `policy:rollback` | step-up, high impact |
| `GET` | `/v1/policies/{policyId}/diff` | `policy:read` | — |
| `POST` | `/v1/policies/simulate` | `policy:simulate` | — |
| `POST` | `/v1/policies/{policyId}/tests/run` | `policy:simulate` | — |
| `POST` | `/v1/policies/{policyId}/tests/preview` | `policy:simulate` | — |

## What each endpoint does

### `GET /v1/policies`

List policies.

Requires `policy:read`.

### `POST /v1/policies`

Create a policy from a template or rule set.

Requires `policy:create`.

### `GET /v1/policies/builder-schema`

Fields, operators and decisions for the Policy Builder.

Requires `policy:read`.

### `PATCH /v1/policies/{policyId}`

Save a new draft version.

Requires `policy:update`.

### `POST /v1/policies/{policyId}/activate`

Activate a version. Requires step-up, a reason and passing tests.

Requires `policy:activate`. Step-up authentication is also required.

Request body:

```json
{
  "version_id": "string",
  "reason": "string"
}
```

### `POST /v1/policies/{policyId}/rollback`

Roll back to a previous version as a new version.

Requires `policy:rollback`. Step-up authentication is also required.

Request body:

```json
{
  "target_version_number": "number",
  "reason": "string"
}
```

### `GET /v1/policies/{policyId}/diff`

Structured diff between two versions.

Requires `policy:read`.

### `POST /v1/policies/simulate`

Simulate a request. No side effects of any kind.

Requires `policy:simulate`.

Request body:

```json
{
  "agentId": "string",
  "tool": "string?",
  "capability": "string?",
  "amount": "number?"
}
```

### `POST /v1/policies/{policyId}/tests/run`

Run the recorded Given/Then test cases.

Requires `policy:simulate`.

### `POST /v1/policies/{policyId}/tests/preview`

Decision for unsaved Given clauses. Read-only; nothing is stored.

Requires `policy:simulate`.

Request body:

```json
{
  "version_id": "string?",
  "cases": "object[] (1-50)"
}
```