Policies - Toktra Documentaion

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).

org_id

string

required

UUID of the organization that owns this policy.

name

string

required

Human-readable policy name.

description

string

Optional description of what the policy does.

model

string

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

action

string

required

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

conditions

object

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

enabled

boolean

required

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

created_at

string

required

ISO 8601 creation timestamp.

updated_at

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

cursor

string

Pagination cursor from next_cursor in the previous response.

limit

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

name

string

required

Human-readable policy name. Maximum 255 characters.

action

string

required

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

description

string

Optional description.

model

string

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

conditions

object

JSON conditions object. See Policy conditions.

enabled

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

name

string

New policy name. Maximum 255 characters.

description

string

New description.

model

string

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

action

string

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

conditions

object

Replacement conditions object.

enabled

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

​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