Events

POST /api/v1/events

Ingest a batch of telemetry events. This is the primary write endpoint used by the Trenchcoat plugin.

Required scope: write:events

Batch limit: Up to 1,000 events per request.

Request

curl -X POST https://app.trenchcoat.com/api/v1/events \
  -H "X-API-Key: ct_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_type": "session_start",
        "session_id": "550e8400-e29b-41d4-a716-446655440000",
        "timestamp": "2024-01-15T10:30:00Z",
        "data": {}
      },
      {
        "event_type": "tool_use",
        "session_id": "550e8400-e29b-41d4-a716-446655440000",
        "timestamp": "2024-01-15T10:30:15Z",
        "data": {
          "tool_name": "Read",
          "tool_input_preview": "/src/components/dashboard/Sidebar.tsx"
        }
      }
    ]
  }'

Request Body

The body must be a JSON object with a single events array.

{
  "events": [
    {
      "event_type": "tool_use",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2024-01-15T10:30:00Z",
      "data": {
        "tool_name": "Read",
        "tool_input_preview": "/src/components/dashboard/Sidebar.tsx"
      }
    }
  ]
}

Field	Type	Required	Description
`event_type`	string	Yes	Type of event (see valid values below)
`session_id`	string (UUID)	Yes	The Claude Code session this event belongs to
`timestamp`	string (ISO 8601)	Yes	When the event occurred
`data`	object	No	Event-specific payload; shape varies by `event_type`

Event Types

Value	When it fires
`session_start`	A new Claude Code session begins
`session_end`	The session ends (user exits or session times out)
`tool_use`	Claude invokes a tool (Read, Edit, Bash, etc.)
`tool_result`	The result of a tool invocation is returned to Claude
`subagent_stop`	A spawned subagent finishes
`assistant_stop`	Claude finishes a response turn

Events within a session should share the same session_id. The session_start event implicitly creates the session record; subsequent events are associated with it.

Responses

Success — 200

{
  "data": {
    "accepted": 42,
    "rejected": 0
  }
}

accepted is the count of events written to the database. rejected is the count of events that failed validation and were dropped. Individual rejection reasons are not returned per event; fix validation errors (see below) and retry.

Validation Error — 400

Returned when the request body is malformed or required fields are missing.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body is invalid.",
    "details": [
      {
        "field": "events[0].session_id",
        "message": "Invalid UUID format"
      },
      {
        "field": "events[2].event_type",
        "message": "Invalid enum value. Expected one of: session_start, session_end, tool_use, tool_result, subagent_stop, assistant_stop"
      }
    ]
  }
}

The entire request is rejected when body-level validation fails. Check details to identify the offending fields.

Batch Too Large — 400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Batch size exceeds limit of 1000 events per request."
  }
}

Split large batches into multiple requests of 1,000 events or fewer.

On this page