Policies API

The Policies API allows you to create, update, and manage permission policies that control how permission requests are handled.

Endpoints

  • GET /v1/policies - List all policies
  • POST /v1/policies - Create a new policy
  • GET /v1/policies/:id - Get a policy
  • PUT /v1/policies/:id - Update a policy
  • DELETE /v1/policies/:id - Delete a policy

List Policies

Get all policies for your account.

Request

GET /v1/policies?agent_id=agent_xxxx&active=true
Authorization: Bearer ak_live_xxxx

Query Parameters

ParameterTypeDescription
agent_idstringFilter by agent ID
activebooleanFilter by active status
limitnumberResults per page (default: 20, max: 100)
cursorstringPagination cursor

Response

{
  "data": [
    {
      "id": "pol_xxxxxxxxxxxx",
      "name": "Auto-approve file reads",
      "description": "Automatically approve small file read operations",
      "agent_id": null,
      "priority": 10,
      "conditions": {
        "action": { "equals": "file.read" },
        "scope.max_size": { "less_than": 1048576 }
      },
      "action": "auto_approve",
      "scope_template": {
        "max_size": 1048576
      },
      "is_active": true,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-15T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create Policy

Create a new permission policy.

Request

POST /v1/policies
Content-Type: application/json
Authorization: Bearer ak_live_xxxx

Body Parameters

FieldTypeRequiredDescription
namestringYesHuman-readable policy name
descriptionstringNoPolicy description
agent_idstringNoApply to specific agent (null = all)
prioritynumberNoEvaluation order (higher = first)
conditionsobjectYesMatching conditions
actionstringYesauto_approve, require_approval, or deny
scope_templateobjectNoDefault scope to apply

Example Request

{
  "name": "Auto-approve internal emails",
  "description": "Auto-approve emails to company domain",
  "priority": 50,
  "conditions": {
    "action": { "equals": "email.send" },
    "context.recipient": { "matches": ".*@mycompany\\.com$" }
  },
  "action": "auto_approve",
  "scope_template": {
    "max_emails": 5,
    "ttl": 600
  }
}

Response

{
  "id": "pol_xxxxxxxxxxxx",
  "name": "Auto-approve internal emails",
  "description": "Auto-approve emails to company domain",
  "agent_id": null,
  "priority": 50,
  "conditions": {
    "action": { "equals": "email.send" },
    "context.recipient": { "matches": ".*@mycompany\\.com$" }
  },
  "action": "auto_approve",
  "scope_template": {
    "max_emails": 5,
    "ttl": 600
  },
  "is_active": true,
  "created_at": "2026-01-28T12:00:00Z",
  "updated_at": "2026-01-28T12:00:00Z"
}

Condition Operators

Policies support various condition operators:

OperatorDescriptionExample
equalsExact match{"equals": "file.read"}
not_equalsNot equal{"not_equals": "admin"}
starts_withString prefix{"starts_with": "file."}
ends_withString suffix{"ends_with": ".csv"}
matchesRegex match{"matches": "^Invoice #\\d+$"}
less_thanNumeric comparison{"less_than": 1048576}
greater_thanNumeric comparison{"greater_than": 0}
inValue in list{"in": ["a", "b"]}
not_inValue not in list{"not_in": ["admin"]}

Update Policy

PUT /v1/policies/:id
Content-Type: application/json
Authorization: Bearer ak_live_xxxx
{
  "name": "Updated policy name",
  "is_active": false
}

Delete Policy

DELETE /v1/policies/:id
Authorization: Bearer ak_live_xxxx

Policy Evaluation Order

When a permission request is received, policies are evaluated in order:

  1. Policies are sorted by priority (highest first)
  2. Agent-specific policies are evaluated before global policies
  3. First matching policy determines the action
  4. If no policy matches, the request requires manual approval

See Also