Events

POST /event

Publish an event to a channel. Supports both Bearer token and API key auth.

Body:

{
  "identifier": "task.started",
  "payload": {"task": "summarize article"},
  "channel_id": 1,
  "agentId": "research-agent",
  "eventType": "agent.start",
  "traceId": "tr_abc123",
  "spanId": "sp_001",
  "metadata": {"tool_name": "web_search"}
}

Required fields: identifier, payload, channel_id

Event types: agent.start, agent.end, agent.message, agent.tool_call.start, agent.tool_call.end, agent.error, agent.handoff, agent.llm.token, custom

Payload size

Bound	Limit	Behavior
Recommended max per event	~64 KB	Keep individual events small for fast retrieval and minimal IoT realtime overhead.
Inline-vs-S3 threshold	380 KB	Events strictly larger than this are stored in S3 instead of inline. Reads work transparently but add a fetch hop.
Hard request cap	6 MB	Anything above is rejected with 413 Payload Too Large. Applies uniformly to POST /event, OTLP, and Sentry envelope endpoints.

If you need to attach a large blob (file uploads, raw model outputs, screenshots), upload it to your own object store and put the URL in the event payload — don’t try to inline it.

GET /event/:channelId/list

List events for a channel with pagination.

Query parameters:

Param	Type	Default	Description
page	int	1	Page number
limit	int	20	Items per page

Response:

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}