Policies API

CRUD operations for governance policies and policy simulation.

List policies

GET /v1/policies

Auth: JWT Bearer Token

curl http://localhost:3000/v1/policies \
  -H "Authorization: Bearer $TOKEN"

Response

[
  {
    "policyId": "pol_abc123",
    "name": "Block destructive ops",
    "description": "Block rm -rf and similar destructive commands",
    "matchConditions": [
      { "field": "toolName", "operator": "contains", "value": "rm" },
      { "field": "inputPayload.command", "operator": "matches", "value": "rm.*-rf" }
    ],
    "action": "block",
    "enabled": true,
    "version": 3,
    "createdAt": "2026-03-01T00:00:00.000Z",
    "updatedAt": "2026-03-15T14:22:00.000Z"
  }
]

---

Get policy

GET /v1/policies/:id

Auth: JWT Bearer Token

---

Get policy version history

GET /v1/policies/:id/versions

Auth: JWT Bearer Token

Returns the version history of a policy, showing all previous versions with their changes.

curl http://localhost:3000/v1/policies/pol_abc123/versions \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "policyId": "pol_abc123",
  "currentVersion": 4,
  "versions": [
    {
      "version": 3,
      "name": "Block dangerous rm commands",
      "description": "Blocks rm -rf and similar destructive commands",
      "action": "block",
      "matchConditions": [
        { "field": "toolName", "operator": "contains", "value": "rm" },
        { "field": "inputPayload.command", "operator": "matches", "value": "rm.*-rf" }
      ],
      "enabled": true,
      "archivedAt": "2026-03-15T14:22:00.000Z",
      "archivedBy": "admin@company.com"
    },
    {
      "version": 2,
      "name": "Warn on rm commands",
      "description": "Warns when rm commands are used",
      "action": "warn",
      "matchConditions": [
        { "field": "toolName", "operator": "contains", "value": "rm" }
      ],
      "enabled": true,
      "archivedAt": "2026-03-10T09:00:00.000Z",
      "archivedBy": "admin@company.com"
    }
  ]
}

---

Create policy

POST /v1/policies

Auth: JWT Bearer Token (admin only)

Request body

{
  "name": "Approve production deploys",
  "description": "Require human approval for production deployments",
  "matchConditions": [
    { "field": "toolName", "operator": "equals", "value": "deploy" },
    { "field": "inputPayload.environment", "operator": "in", "value": ["production", "prod"] }
  ],
  "action": "require_approval",
  "enabled": true
}

Field	Type	Required	Description
name	string	Yes	Policy name
description	string	No	Policy description
presetId	string	No	Source preset ID when created from preset/gallery/pack
matchConditions	array	Yes	Conditions that must all match
matchConditions[].field	string	Yes	Field to match on
matchConditions[].operator	string	Yes	Match operator
matchConditions[].value	any	Depends	Value to match against
action	string	Yes	allow, warn, block, or require_approval
scope	string	No	all or action_only
rateLimit	object	No	Rate limit configuration
enabled	boolean	Yes	Whether the policy is active

Policies also include the following read-only fields in responses:

Field	Type	Description
version	number	Auto-incremented version number (starts at 1)
updatedAt	ISO 8601	Timestamp of the last update

---

Update policy

PATCH /v1/policies/:id

Auth: JWT Bearer Token (admin only)

Send only the fields you want to update:

curl -X PATCH http://localhost:3000/v1/policies/pol_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

---

Delete policy

DELETE /v1/policies/:id

Auth: JWT Bearer Token (admin only)

curl -X DELETE http://localhost:3000/v1/policies/pol_abc123 \
  -H "Authorization: Bearer $TOKEN"

---

Simulate policy

POST /v1/policies/simulate

Auth: JWT Bearer Token (reviewer or admin)

Test which policies would match a hypothetical tool call without affecting real agents.

curl -X POST http://localhost:3000/v1/policies/simulate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "toolName": "deploy",
    "inputPayload": {
      "environment": "production",
      "service": "api"
    }
  }'

Response

{
  "matchedPolicies": [
    {
      "policyId": "pol_abc123",
      "name": "Approve production deploys",
      "action": "require_approval"
    }
  ],
  "resultingAction": "require_approval"
}

---

Policy presets

GET /v1/policy-presets

Auth: JWT Bearer Token

Returns available policy presets grouped by category that can be enabled with one click.

---

Policy packs

Browse curated packs:

GET /v1/policy-presets/packs

Auth: JWT Bearer Token

Each pack includes metadata plus:

• presetCount: number of presets in the pack
• activatedCount: number currently active for the org (via presetId)

Activate a full pack:

POST /v1/policy-presets/packs/:packId/activate

Auth: JWT Bearer Token (admin only)

Returns only the newly created policy objects. Already-activated presets are skipped automatically.