Events

Events are the atomic unit of observability. Every action your agent takes is captured as an event within a session.

POST/v1/events

Ingest a single agent event. The event is validated, normalized, and stored under the authenticated tenant.

Request body:

Field	Type	Required	Description
`eventId`	UUID	Yes	Client-generated unique identifier
`agentId`	string	Yes	Agent identifier (1–255 chars)
`sessionId`	string	Yes	Session identifier (1–255 chars)
`sourceTimestamp`	ISO 8601	Yes	When the event occurred
`category`	string	Yes	Event category (see Event Schema)
`schemaVersion`	string	Yes	Schema version (`"1.0"`)
`payload`	object	Yes	Category-specific data
`previousHash`	string	No	Hash of the previous event for chain integrity
`traceId`	string	No	Distributed trace ID
`runId`	string	No	Execution run ID
`correlationId`	string	No	Cross-session correlation ID
`parentEventId`	UUID	No	Parent event for causal chains
`causationEventId`	UUID	No	Direct cause event
`agentVersion`	string	No	Agent software version
`toolType`	string	No	Tool classification
`targetSystem`	string	No	Target system identifier
`operation`	string	No	Operation type
`initiatorType`	string	No	Who initiated (`human`, `agent`, `system`)
`initiatorId`	string	No	Initiator identifier

Example request:


{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "agentId": "support-bot",
  "sessionId": "session-001",
  "sourceTimestamp": "2025-01-15T10:30:00Z",
  "category": "tool_api",
  "schemaVersion": "1.0",
  "payload": {
    "toolName": "database_query",
    "argumentsHash": "a1b2c3d4...",
    "responseStatus": 200,
    "endpoint": "/api/customers"
  },
  "toolType": "database",
  "targetSystem": "crm",
  "operation": "read"
}

Idempotency: Sending the same eventId for the same tenant returns 202 with the original receivedAt. No duplicate is created.

Schema enforcement: The request body is validated with strict() — unknown top-level fields are rejected.