Events API v1

POST /api/v1/events

v1 is intentionally strict and opinionated. Use it when you only need canonical product-lifecycle events.

Allowed event types

• user_signed_up
• user_active
• session_start
• session_end
• user_deleted

Request shape

Required fields:

• event_type — one of the canonical types above (flat format)
• subject_type
• subject_id
• occurred_at (ISO-8601)

Optional:

• metadata (object)
• external_id (idempotency key)

Response

The response auto-splits the flat event_type into separate fields:

• event_type — entity noun (e.g. session)
• action — verb (e.g. start)
• canonical_name — joined original value (e.g. session_start)

Example

curl -X POST "/api/v1/events" \
  -H "Authorization: Bearer YOUR_EVENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "session_start",
    "subject_type": "user",
    "subject_id": "user_123",
    "occurred_at": "2026-02-10T12:00:00Z",
    "external_id": "my-app:session_start:user_123:1739188800",
    "metadata": {
      "session_id": "sess_1"
    }
  }'

Response:

{
  "data": {
    "uuid": "evt_abc123",
    "event_type": "session",
    "action": "start",
    "canonical_name": "session_start",
    "source": "api",
    "subject_type": "user",
    "subject_id": "user_123",
    "occurred_at": "2026-02-10T12:00:00Z",
    "external_id": "my-app:session_start:user_123:1739188800"
  }
}

When to use v2 instead

Use Events API v2 if you need:

• custom event types (for example project_created)
• separate event_type + action fields in the request
• batch ingestion