Events API
Send behavioral events to the Thoth audit ledger with POST /v1/events/batch.
The SDKs batch and send events for you. Call this endpoint directly only for a custom integration or a non-SDK event source. It uses your unified tenant API base URL; see Authentication.
Send a batch of events
POST/v1/events/batch
Queues behavioral events for ingestion and returns 202 Accepted. Retention and
export pipelines depend on the environment. An accepted batch is not a verified
signed receipt.
The body is a JSON array of events. An object of the form {"events": [...]}
is also accepted for compatibility. Every event in a batch must belong to one
tenant.
Authenticate with a runtime key, or with X-Thoth-Event-Ingest-Token when a
dedicated ingest token is configured.
Event fields
tenant_idstringrequired
session_idstringrequired
user_idstringrequired
source_typestringrequired
agent_tool_call for a tool call through an SDK, or agent_llm_invocation for
a model completion inside an agent.
event_typestringrequired
TOOL_CALL_PRE (before a tool runs, after the policy check passes),
TOOL_CALL_POST (after it returns), TOOL_CALL_BLOCK (enforcement refused the
call) or LLM_INVOCATION (a model completion).
approved_scopestring[]required
session_tool_callsstring[]required
enforcement_modestringrequired
observe, progressive, step_up or block.contentstringrequired
TOOL_CALL_PRE) or result (TOOL_CALL_POST).occurred_atstring (ISO 8601)required
event_idstring
Unique event ID; a UUID v4 is recommended. If omitted, the server derives a stable hash-based ID. Keep IDs stable across retries.
agent_idstring
tool_namestring
metadataobject
Key-value pairs for your own use. For token-spend analytics on
LLM_INVOCATION events, include prompt_tokens, completion_tokens,
total_tokens, provider and model_name. camelCase aliases such as
promptTokens are normalized.
Returns
statusstring
"accepted" on success.queuedstring
replay_droppedstring
A malformed body or event returns 400 with a detail message naming the
problem, for example the index of an event missing tenant_id.
Batching and retries
Send up to 100 events per request. Ingestion is best effort: queued reports
how many events were forwarded. Duplicates within a request are removed, and
short-window replays are dropped when replay protection is enabled, so retry a
failed batch with the same event_id values.