Events API

Endpoints

Async Event Ingestion

The primary ingestion endpoint. Events are queued to a Redis Stream for background processing, providing sub-50ms response times. Use this for production workloads.

curl -X POST https://YOUR_API_DOMAIN/api/v1/ingest/events \
  -H "X-API-Key: bq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "purchase_completed",
    "participant_id": "user_123",
    "properties": {
      "amount": 49.99,
      "currency": "USD",
      "product_id": "prod_abc"
    },
    "timestamp": "2026-04-10T10:30:00Z"
  }'

{
  "accepted": true,
  "message_id": "1707900600000-0"
}

Batch Ingestion

Submit up to 100 events in a single request. Each event is independently validated and queued. Partial failures are reported per-event.

curl -X POST https://YOUR_API_DOMAIN/api/v1/ingest/events/batch \
  -H "X-API-Key: bq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "page_view",
        "participant_id": "user_123",
        "properties": {"page": "/products"}
      },
      {
        "event_name": "add_to_cart",
        "participant_id": "user_123",
        "properties": {"product_id": "prod_abc", "quantity": 1}
      },
      {
        "event_name": "purchase_completed",
        "participant_id": "user_123",
        "properties": {"amount": 49.99, "currency": "USD"}
      }
    ]
  }'

{
  "accepted": 3,
  "rejected": 0,
  "message_ids": [
    "1707900600000-0",
    "1707900600000-1",
    "1707900600000-2"
  ]
}

Synchronous Ingestion

Processes the event synchronously and returns the resulting event ID and fact ID. Best for testing, debugging, and workflows that need immediate confirmation of processing.

curl -X POST https://YOUR_API_DOMAIN/api/v1/ingest/events/sync \
  -H "X-API-Key: bq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "level_completed",
    "participant_id": "user_123",
    "properties": {
      "level": 5,
      "score": 9200,
      "time_seconds": 120
    }
  }'

{
  "event_id": "evt_abc123",
  "fact_id": "fact_def456",
  "fact_type": "custom.level_completed",
  "processed_at": "2026-04-10T10:30:01Z"
}

Event Schema

Events are validated with soft validation — unknown event names are auto-discovered and accepted. The required fields are: