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`	No	Unique event identifier. Recommended: UUID v4. If omitted, server derives a stable hash-based ID.
`tenant_id`	`string`	Yes	Your Thoth tenant identifier
`agent_id`	`string`	No	Agent identifier
`session_id`	`string`	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

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
`TOOL_CALL_BLOCK`	Emitted when enforcement blocks a proposed tool call
`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",
  "replay_dropped": "0"
}

Field	Type	Description
`status`	`string`	Always `"accepted"` on success
`queued`	`string`	Number of events queued for ingestion
`replay_dropped`	`string`	Number of events dropped by replay/dedup guards in this request

Error response

HTTP/1.1 400 Bad Request
 
{
  "detail": "Invalid event at index 0: missing tenant_id"
}

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. Batch processing is best-effort: the API returns queued with the number of events successfully forwarded for ingestion.

Idempotency

The API deduplicates duplicate events within the same request and can drop short-window replays when replay protection is enabled. If your queue is FIFO, queue-level deduplication also applies. Always generate stable event_id values when retrying batches.

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"
    }
  ]'