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.