Policies API

The Policies API lets you define governance policies for your workspace. Policies enforce rules around deployments, cost thresholds, and approval workflows. You can activate, deactivate, and promote enforcement levels programmatically.

All endpoints are under /api/policies and require authentication.

Templates and Validation

GET/api/policies/templatesAuth required

Get available policy templates to use as starting points.

GET/api/policies/attention-countAuth required

Get the count of policies that need attention or review.

POST/api/policies/validate-conditionsAuth required

Validate condition providers before creating a policy.


// Request body
{
  "conditions": {
    "provider": "github",
    "check": "branch_protection",
    "params": { "branch": "main" }
  }
}

CRUD Operations

POST/api/policiesAuth required

Create a new policy.

GET/api/policiesAuth required

List all policies in the workspace.

GET/api/policies/:idAuth required

Get a single policy by ID.

PUT/api/policies/:idAuth required

Update an existing policy.

DELETE/api/policies/:idAuth required

Delete a policy. Requires owner or admin role. Returns 204 on success.

Only workspace owners and admins can delete policies. Members will receive a 403 response.

Lifecycle Management

POST/api/policies/:id/activateAuth required

Activate a policy so it begins evaluating.

POST/api/policies/:id/deactivateAuth required

Deactivate a policy. It will stop evaluating until reactivated.

POST/api/policies/:id/promoteAuth required

Promote the policy to the next enforcement level.

POST/api/policies/:id/reset-circuit-breakerAuth required

Reset the circuit breaker if the policy has tripped.

Policies follow a progressive enforcement model. Use promote to move from warn to block mode after validating behavior.

Evaluations

GET/api/policies/:id/evaluationsAuth required

Get evaluation history for a policy. Supports pagination (max 100 per page).


GET /api/policies/:id/evaluations?page=1&pageSize=50

Example response


{
  "evaluations": [
    {
      "id": "eval_abc123",
      "result": "pass",
      "timestamp": "2026-04-30T10:15:00Z",
      "context": { "pr": 42, "repo": "acme/api" }
    }
  ],
  "total": 128,
  "page": 1,
  "pageSize": 50
}

Bulk Operations

POST/api/policies/pause-allAuth required

Pause all active policies in the workspace.

POST/api/policies/resume-allAuth required

Resume all paused policies in the workspace.

Bulk pause and resume affect every policy in the workspace. Use with care during incidents or maintenance windows.