Policies

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

string

required

Unique policy identifier (UUID).

string

required

UUID of the organization that owns this policy.

string

required

Human-readable policy name.

string

Optional description of what the policy does.

string

Target LLM model (e.g., gpt-4). null means the policy applies to all models.

string

required

Action to take when the policy is triggered. One of: allow, block, alert, require_approval.

object

JSON object defining the conditions under which the policy fires. See Policy conditions below.

boolean

required

Whether the policy is currently active. Disabled policies are not evaluated.

string

required

ISO 8601 creation timestamp.

string

required

ISO 8601 last-updated timestamp.

Policy conditions

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

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

string

Pagination cursor from next_cursor in the previous response.

integer

default:"25"

Items per page (1–100).

Example

curl "https://api.toktra.io/v1/policies?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

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

string

required

Human-readable policy name. Maximum 255 characters.

string

required

Action to take when the policy fires. One of: allow, block, alert, require_approval.

string

Optional description.

string

Target model name. Omit or set to null to apply to all models.

object

JSON conditions object. See Policy conditions.

boolean

default:"true"

Whether the policy is active immediately after creation.

Example

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
  }'

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"])

Response (201 Created)

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

string

required

Policy UUID.

Example

curl "https://api.toktra.io/v1/policies/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (200 OK)

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

string

required

Policy UUID.

Request body

string

New policy name. Maximum 255 characters.

string

New description.

string

New target model. Set to null to apply to all models.

string

New action: allow, block, alert, or require_approval.

object

Replacement conditions object.

boolean

Enable or disable the policy.

Example

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

string

required

Policy UUID.

Example

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.

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.

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

Overview

Endpoints

The Policy object

Policy conditions

List policies

Query parameters

Example

Create a policy

Request body

Example

Get a policy

Path parameters

Example

Update a policy

Path parameters

Request body

Example

Delete a policy

Path parameters

Example

Error responses

​The Policy object

​Policy conditions

​List policies

​Query parameters

​Example

​Create a policy

​Request body

​Example

​Get a policy

​Path parameters

​Example

​Update a policy

​Path parameters

​Request body

​Example

​Delete a policy

​Path parameters

​Example

​Error responses

The Policy object

Policy conditions

List policies

Query parameters

Example

Create a policy

Request body

Example

Get a policy

Path parameters

Example

Update a policy

Path parameters

Request body

Example

Delete a policy

Path parameters

Example

Error responses