Event schema

Every source is normalized into one canonical event, schema version 1.0. The schema is defined with Zod in packages/event-schema and validated on ingestion.

Send events

POST /api/ingest/events
Authorization: Bearer tm_ing_…
Content-Type: application/json

{ "events": [ { … }, { … } ] }

Up to 500 events per request. The organization is taken from the key, never from the payload.

Response:

{
  "accepted": 2, "duplicates": 0, "rejected": 0,
  "results": [{ "event_id": "…", "status": "accepted" }],
  "findings": [{ "event_id": "…", "policy_id": "destructive-commands", "severity": "high", "title": "…" }]
}

Invalid events are rejected individually with a reason; valid events in the same batch are still stored. Sending an event_id twice returns duplicate and stores nothing new.

Status Meaning
200 Batch processed (check per-event results)
400 Malformed body or more than 500 events
401 Missing, invalid or revoked key
429 Rate limited, or quota_exceeded for the month

Event

{
  "schema_version": "1.0",
  "event_id": "cc_3f6c…",
  "type": "tool.completed",
  "occurred_at": "2026-11-15T10:02:19.852Z",
  "source": { "kind": "claude-code.hook", "version": "0.1.0", "raw_event": "PostToolUse", "collection_level": "metadata" },
  "agent": { "name": "claude-code", "type": "claude-code", "model": "…" },
  "session": { "id": "7f3a91c2-…" },
  "tool": { "name": "Bash", "use_id": "toolu_…", "category": "vcs.commit" },
  "command": { "categories": ["vcs.commit"], "programs": ["git"], "opaque": false },
  "outcome": { "status": "success", "duration_ms": 80, "exit_code": 0 },
  "repository": { "slug": "github.com/acme/payments-api", "branch": "fix/refund-rounding", "head_sha": "a41c9e7…" },
  "correlation": { "commit_shas": ["a41c9e7…"] }
}

Required fields

schema_version, event_id (8–128 chars, unique per organization), type, occurred_at (ISO 8601 with offset), source.kind, agent.name, session.id.

Types

session.started, session.ended, turn.completed, tool.requested, tool.completed, tool.failed, tool.blocked, subagent.started, subagent.stopped, error.reported, usage.reported, custom (requires custom_type).

Source kinds

claude-code.hook, claude-code.otel, otlp, sdk.typescript, sdk.python, api, demo. The provider's own name for the event is preserved in source.raw_event.

Optional blocks

Block Contents
tool name, use_id (pairs a request with its result), category, mcp_server
command categories, programs, hosts, sensitive_paths, opaque, redacted_text (extended level only)
files[] path, operation (read / write / edit / delete / search), sensitive
outcome status (success / failure / blocked / unknown), exit_code, duration_ms, error_type
subagent id, type
repository slug (host/owner/name), branch, head_sha
environment Declared name; verified server-side
correlation trace_id, span_id, prompt_id, commit_shas[]
enforcement mode, decision, confirmed, policy_id
usage token counts, reported_cost_usd (source-reported only)
metadata Flat map of scalars. Only allowlisted keys are kept; values are redacted.

sequence is an optional per-session counter from the sender. The server assigns its own organization-wide sequence number to every stored event, used as the cursor for the realtime stream.

Realtime stream

GET /api/orgs/:org/stream is a Server-Sent Events endpoint (session cookie required). Each event message's id is the event's sequence number. A client that reconnects with Last-Event-ID (browsers do this automatically) or ?cursor=<seq> receives exactly the events it missed, in order, before live messages resume.