Events API

Document the POST /v1/events/batch endpoint — behavioral event ingestion for the Thoth audit ledger.

POST /v1/events/batch

Emit one or more behavioral events to the Thoth audit ledger. Events are stored for 90 days and can be consumed through API and SIEM export pipelines.

The SDKs call this endpoint automatically — you typically do not need to call it directly.

Request

POST /v1/events/batch
Authorization: Bearer thoth_live_your_key_here
Content-Type: application/json

[
  {
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "acme-corp",
    "agent_id": "invoice-processor-v2",
    "session_id": "session-uuid",
    "user_id": "user-123",
    "source_type": "agent_tool_call",
    "event_type": "TOOL_CALL_PRE",
    "tool_name": "submit_payment",
    "approved_scope": ["search_docs", "read_invoice"],
    "enforcement_mode": "progressive",
    "session_tool_calls": ["search_docs", "read_invoice"],
    "content": "{\"invoice_id\": \"INV-001\", \"amount\": 1500.00}",
    "metadata": { "request_id": "req-abc123" },
    "occurred_at": "2026-03-13T10:00:00.000Z"
  }
]

Legacy wrapper payloads are also accepted:

{ "events": [/* BehavioralEvent */] }

Request body

The endpoint accepts either:

A JSON array of BehavioralEvent objects (canonical).
A JSON object with an events array (legacy compatibility).

BehavioralEvent schema

Field	Type	Required	Description
`event_id`	`string (UUID)`	Yes	Unique event identifier. Use UUID v4.
`tenant_id`	`string`	Yes	Your Thoth tenant identifier
`agent_id`	`string`	No	Agent identifier
`session_id`	`string (UUID)`	Yes	Session this event belongs to
`user_id`	`string`	Yes	User who initiated the agent action
`source_type`	`SourceType`	Yes	Origin of the event
`event_type`	`EventType`	Yes	Type of event
`tool_name`	`string`	No	Name of the tool being called (if applicable)
`approved_scope`	`string[]`	Yes	List of approved tool names for this session
`enforcement_mode`	`EnforcementMode`	Yes	Enforcement mode in effect
`session_tool_calls`	`string[]`	Yes	Tool names already called in this session (for context)
`content`	`string`	Yes	JSON-serialized arguments (PRE) or result (POST)
`metadata`	`object`	No	Arbitrary key-value pairs for your own use
`occurred_at`	`string (ISO 8601)`	Yes	Timestamp of the event

For reliable token spend analytics on LLM_INVOCATION events, include:

metadata.prompt_tokens
metadata.completion_tokens
metadata.total_tokens
metadata.provider
metadata.model_name

CamelCase metadata aliases (for example promptTokens, completionTokens, totalTokens) are normalized server-side.

SourceType values

Value	Description
`agent_tool_call`	AI agent calling a tool via Thoth SDK
`agent_llm_invocation`	LLM completion call within an agent
`slack`	Event originating from a Slack message
`teams`	Event originating from a Microsoft Teams message
`signal`	Event originating from a Signal message

EventType values

Value	Description
`TOOL_CALL_PRE`	Emitted before a tool executes (after policy check passes)
`TOOL_CALL_POST`	Emitted after a tool returns successfully
`LLM_INVOCATION`	Emitted when the agent makes an LLM completion call

EnforcementMode values

Value	Description
`observe`	Logging mode — no enforcement
`progressive`	Escalating enforcement
`step_up`	Human approval required
`block`	Immediate rejection for violations

Response

HTTP/1.1 202 Accepted
Content-Type: application/json
 
{
  "status": "accepted",
  "queued": "1"
}

Field	Type	Description
`status`	`string`	Always `"accepted"` on success
`queued`	`string`	Number of events queued for ingestion

Error response

HTTP/1.1 400 Bad Request
 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "events[0].sessionId: must be a valid UUID",
    "requestId": "req_abc123"
  }
}

The SDK batches events automatically in a background queue. When calling the API directly, batch up to 100 events per request to minimize HTTP overhead. Events within a batch are processed atomically — if the batch is accepted, all events are ingested.

Idempotency

If you retry a batch after a network error, duplicate event_id values are silently deduplicated by the server. Always generate a stable UUID per event and retry the same batch without changing event_id values.

Example (curl)

curl -X POST https://api.atensecurity.com/v1/events/batch \
  -H "Authorization: Bearer $THOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "event_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "acme-corp",
      "agent_id": "invoice-processor-v2",
      "session_id": "session-uuid-here",
      "user_id": "system",
      "source_type": "agent_tool_call",
      "event_type": "TOOL_CALL_PRE",
      "tool_name": "search_docs",
      "approved_scope": ["search_docs"],
      "enforcement_mode": "progressive",
      "session_tool_calls": [],
      "content": "{\"query\": \"invoice #INV-001\"}",
      "occurred_at": "2026-03-13T10:00:00.000Z"
    }
  ]'