Overview - Toktra Documentaion

The Toktra Public API gives you programmatic access to your organization’s AI governance data — usage records, policies, budgets, users, and alerts. All endpoints are served over HTTPS and return JSON.

Base URL

https://api.toktra.io/v1

A staging environment is available at https://api.staging.toktra.io/v1 for testing integrations before you go live.

Authentication

The API uses OAuth 2.0 Bearer tokens obtained via the client_credentials grant. Pass your token in the Authorization header on every request:

Authorization: Bearer YOUR_ACCESS_TOKEN

You can also authenticate with a long-lived API key as a simpler alternative for server-to-server integrations. See Authentication for full details on both methods.

Rate limiting

The API enforces a limit of 1,000 requests per minute per API key. Every response includes rate limit headers so you can track your consumption:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you exceed the limit, the API returns a 429 Too Many Requests response along with a Retry-After header indicating how many seconds to wait before retrying.

Pagination

List endpoints use cursor-based pagination. This approach is stable and efficient for large datasets — pages don’t shift when records are added or removed. Pass cursor and limit as query parameters:

Parameter	Type	Default	Description
`cursor`	string	—	Opaque cursor from `next_cursor` in the previous response. Omit for the first page.
`limit`	integer	25	Items per page. Min `1`, max `100`.

Every paginated response includes:

{
  "items": [...],
  "next_cursor": "eyJpZCI6IjAxOTQ1YjM2LTQ1NjctNzAwMC04MDAwLTAwMDAwMDAwMDAwMCJ9",
  "has_more": true,
  "total_count": 142
}

When next_cursor is null, you have reached the last page. See Pagination for a full walkthrough.

Response format

All responses are JSON with Content-Type: application/json. Successful responses return the resource directly or a paginated wrapper object.

Errors

The API returns standard HTTP status codes. Error bodies follow this schema:

{
  "error": "not_found",
  "message": "Policy with ID 01945b36-4567-7000-8000-000000000000 not found",
  "status_code": 404
}

Status code	Error type	Meaning
`400`	`bad_request`	Invalid request body or query parameters
`401`	`unauthorized`	Missing, invalid, or expired access token
`403`	`forbidden`	Token lacks permission for this resource
`404`	`not_found`	Resource does not exist
`429`	`rate_limited`	Rate limit exceeded — check `Retry-After`
`500`	`internal_error`	Unexpected server error

Always check the message field for a human-readable explanation of what went wrong. It typically names the specific field or resource involved.

Versioning

The current stable version is /v1, which is generally available (GA). Breaking changes will only be introduced in a new major version (/v2, etc.). Additive changes — new fields and new optional parameters — may be made to /v1 at any time without notice.

Pin your integrations to /v1 explicitly. The unversioned base URL https://api.toktra.io is not supported.

​Base URL

​Authentication

​Rate limiting

​Pagination

​Response format

​Errors

​Versioning

Base URL

Authentication

Rate limiting

Pagination

Response format

Errors

Versioning