API Reference

Overview of the Thoth REST API at https://api.atensecurity.com — authentication, base URL, and available endpoints.

Base URL

https://api.atensecurity.com

All endpoints use HTTPS. There is no HTTP fallback.

Authentication

All API requests must include a bearer token in the Authorization header:

Authorization: Bearer thoth_live_your_key_here

API keys are prefixed with thoth_live_ for production and thoth_test_ for test environments. Generate keys through the Thoth control-plane API.

Key creation (control plane)

Create keys through the Thoth control-plane endpoint:

POST /:tenant-id/thoth/api-keys
Request fields:
- name (optional)
- scope_level: organization | fleet | endpoint | agent
- scope_target_id (required for fleet/endpoint/agent scopes)
- permissions: any subset of read, write, execute

The plaintext key is returned once at creation and is not retrievable afterward.

Key scopes

Scope	Capabilities
`events:write`	POST events to `/v1/events/batch`
`enforcement:read`	POST to `/v1/enforce`
`step-up:read`	GET `/v1/enforce/hold/{hold_token}`
`admin`	All scopes + control-plane administration access

Standard SDK API keys have all three non-admin scopes.

Request format

All endpoints accept and return application/json. Request bodies must include a Content-Type: application/json header.

Response codes

Code	Meaning
`200 OK`	Request succeeded (enforcement check, step-up poll)
`202 Accepted`	Events queued for ingestion (`POST /v1/events/batch`)
`400 Bad Request`	Malformed request body (see `error.message`)
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Valid key but insufficient scope
`429 Too Many Requests`	Rate limit exceeded (see `Retry-After` header)
`500 Internal Server Error`	Transient server error — retry with exponential backoff

Error response body

{
  "error": {
    "code": "INVALID_TENANT",
    "message": "tenant 'acme' not found",
    "requestId": "req_abc123"
  }
}

Rate limits

Endpoint	Limit
`POST /v1/events/batch`	1,000 req/min per tenant
`POST /v1/enforce`	500 req/min per tenant
`GET /v1/enforce/hold/{token}`	200 req/min per tenant

Rate limit headers are returned on every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1710334800

Available endpoints

Method	Path	Purpose
`POST`	`/v1/events/batch`	Emit one or more behavioral events
`POST`	`/v1/enforce`	Check enforcement policy for a tool call
`GET`	`/v1/enforce/hold/{token}`	Poll step-up approval status
`GET`	`/healthz`	Health check (no auth required)

SDKs vs. direct API

Most users interact with Thoth exclusively through the language SDKs, which handle authentication, batching, retries, and error translation automatically. Use the raw API directly if you are:

Building a custom SDK or integration
Auditing events from a non-SDK source (e.g. a log aggregator)
Implementing a step-up approval webhook

See Events and Enforcement for detailed endpoint documentation.

API Reference

On this page