> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

> Create and manage AI usage policies for your organization.

Policies define rules that govern how users in your organization can use LLM models. When a policy is triggered, Toktra takes the configured action — allowing, blocking, alerting, or requiring approval for the request.

## The Policy object

<ResponseField name="id" type="string" required>
  Unique policy identifier (UUID).
</ResponseField>

<ResponseField name="org_id" type="string" required>
  UUID of the organization that owns this policy.
</ResponseField>

<ResponseField name="name" type="string" required>
  Human-readable policy name.
</ResponseField>

<ResponseField name="description" type="string">
  Optional description of what the policy does.
</ResponseField>

<ResponseField name="model" type="string">
  Target LLM model (e.g., `gpt-4`). `null` means the policy applies to all models.
</ResponseField>

<ResponseField name="action" type="string" required>
  Action to take when the policy is triggered. One of: `allow`, `block`, `alert`, `require_approval`.
</ResponseField>

<ResponseField name="conditions" type="object">
  JSON object defining the conditions under which the policy fires. See [Policy conditions](#policy-conditions) below.
</ResponseField>

<ResponseField name="enabled" type="boolean" required>
  Whether the policy is currently active. Disabled policies are not evaluated.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 last-updated timestamp.
</ResponseField>

### Policy conditions

The `conditions` object expresses the criteria that must match for the policy to fire. Conditions use key-value pairs with operators:

```json theme={null}
{
  "department": {
    "not_in": ["engineering"]
  }
}
```

This fires when the requesting user's department is **not** in the `engineering` list.

***

## List policies

Returns a cursor-paginated list of all policies in your organization.

```
GET https://api.toktra.io/v1/policies
```

### Query parameters

<ParamField query="cursor" type="string">
  Pagination cursor from `next_cursor` in the previous response.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Items per page (1–100).
</ParamField>

### Example

```bash theme={null}
curl "https://api.toktra.io/v1/policies?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response**

```json theme={null}
{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "org_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
      "name": "Restrict GPT-4 to Engineering",
      "description": "Blocks GPT-4 access for users outside the engineering department.",
      "model": "gpt-4",
      "action": "block",
      "conditions": {
        "department": {
          "not_in": ["engineering"]
        }
      },
      "enabled": true,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-10T09:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total_count": 1
}
```

***

## Create a policy

Creates a new policy for your organization.

```
POST https://api.toktra.io/v1/policies
```

### Request body

<ParamField body="name" type="string" required>
  Human-readable policy name. Maximum 255 characters.
</ParamField>

<ParamField body="action" type="string" required>
  Action to take when the policy fires. One of: `allow`, `block`, `alert`, `require_approval`.
</ParamField>

<ParamField body="description" type="string">
  Optional description.
</ParamField>

<ParamField body="model" type="string">
  Target model name. Omit or set to `null` to apply to all models.
</ParamField>

<ParamField body="conditions" type="object">
  JSON conditions object. See [Policy conditions](#policy-conditions).
</ParamField>

<ParamField body="enabled" type="boolean" default="true">
  Whether the policy is active immediately after creation.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.toktra.io/v1/policies \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Restrict GPT-4 to Engineering",
      "description": "Blocks GPT-4 access for users outside the engineering department.",
      "model": "gpt-4",
      "action": "block",
      "conditions": {
        "department": {
          "not_in": ["engineering"]
        }
      },
      "enabled": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.toktra.io/v1/policies",
      headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
      json={
          "name": "Restrict GPT-4 to Engineering",
          "description": "Blocks GPT-4 access for users outside the engineering department.",
          "model": "gpt-4",
          "action": "block",
          "conditions": {
              "department": {"not_in": ["engineering"]}
          },
          "enabled": True,
      },
  )
  policy = response.json()
  print(policy["id"])
  ```
</CodeGroup>

**Response** (`201 Created`)

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "org_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
  "name": "Restrict GPT-4 to Engineering",
  "description": "Blocks GPT-4 access for users outside the engineering department.",
  "model": "gpt-4",
  "action": "block",
  "conditions": {
    "department": {
      "not_in": ["engineering"]
    }
  },
  "enabled": true,
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-01-10T09:00:00Z"
}
```

***

## Get a policy

Returns a single policy by ID.

```
GET https://api.toktra.io/v1/policies/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  Policy UUID.
</ParamField>

### Example

```bash theme={null}
curl "https://api.toktra.io/v1/policies/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response** (`200 OK`)

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "org_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
  "name": "Restrict GPT-4 to Engineering",
  "description": "Blocks GPT-4 access for users outside the engineering department.",
  "model": "gpt-4",
  "action": "block",
  "conditions": {
    "department": {
      "not_in": ["engineering"]
    }
  },
  "enabled": true,
  "created_at": "2025-01-10T09:00:00Z",
  "updated_at": "2025-01-10T09:00:00Z"
}
```

***

## Update a policy

Updates an existing policy. All fields are optional — only the fields you include are changed.

```
PUT https://api.toktra.io/v1/policies/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  Policy UUID.
</ParamField>

### Request body

<ParamField body="name" type="string">
  New policy name. Maximum 255 characters.
</ParamField>

<ParamField body="description" type="string">
  New description.
</ParamField>

<ParamField body="model" type="string">
  New target model. Set to `null` to apply to all models.
</ParamField>

<ParamField body="action" type="string">
  New action: `allow`, `block`, `alert`, or `require_approval`.
</ParamField>

<ParamField body="conditions" type="object">
  Replacement conditions object.
</ParamField>

<ParamField body="enabled" type="boolean">
  Enable or disable the policy.
</ParamField>

### Example

```bash theme={null}
curl -X PUT "https://api.toktra.io/v1/policies/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "alert", "enabled": true}'
```

**Response** (`200 OK`) — returns the updated Policy object.

***

## Delete a policy

Permanently deletes a policy. This action cannot be undone.

```
DELETE https://api.toktra.io/v1/policies/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  Policy UUID.
</ParamField>

### Example

```bash theme={null}
curl -X DELETE "https://api.toktra.io/v1/policies/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response** — `204 No Content` with an empty body.

<Warning>
  Deleting a policy is permanent. If you want to stop a policy from firing without losing its configuration, set `enabled` to `false` using the update endpoint instead.
</Warning>

***

## Error responses

| Status | Error          | Description                             |
| ------ | -------------- | --------------------------------------- |
| `400`  | `bad_request`  | Missing required field or invalid value |
| `401`  | `unauthorized` | Invalid or expired token                |
| `404`  | `not_found`    | Policy ID does not exist                |
| `429`  | `rate_limited` | Rate limit exceeded                     |