Skip to main content

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.

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:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per minute
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix 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:
ParameterTypeDefaultDescription
cursorstring—Opaque cursor from next_cursor in the previous response. Omit for the first page.
limitinteger25Items 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 codeError typeMeaning
400bad_requestInvalid request body or query parameters
401unauthorizedMissing, invalid, or expired access token
403forbiddenToken lacks permission for this resource
404not_foundResource does not exist
429rate_limitedRate limit exceeded — check Retry-After
500internal_errorUnexpected 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.