Reference / REST API

Policy API

Author, version, simulate, test, activate and roll back policy.

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.

#Endpoints

#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:

jsonCopy
{
  "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:

jsonCopy
{
  "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:

jsonCopy
{
  "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:

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