> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Ingest customer events for real-time trigger evaluation, with a capped per-tenant Redis Stream for external consumers.

The Events API ingests customer events into the platform's event bus. Events are evaluated against active trigger rules in real time **and** published to a per-tenant Redis Stream. Supports single events and batches of up to 100. Rate limited to 500 requests/min. **Editor or Admin.**

<Note>
  **Trigger evaluation does not depend on the stream.** The route calls the trigger
  engine directly and treats the stream publish as non-critical, so a `streamId` of
  `null` never means a missed trigger.

  **No stream consumer ships with the platform.** `events:<tenantId>` is a fan-out
  sink for your own consumers. Because nothing reads it by default, each stream is
  capped with `MAXLEN ~` (`EVENT_STREAM_MAXLEN`, default `10000` entries) — before
  2026-08-15 it was uncapped and grew until Redis ran out of memory. If you attach a
  consumer, acknowledge each message **after** processing it so Redis' pending-entries
  list can redeliver on a crash.
</Note>

## POST /api/v1/events

Ingest one or more customer events.

### Request Body — Single Event

| Field        | Type   | Required | Description                                                       |
| ------------ | ------ | -------- | ----------------------------------------------------------------- |
| `eventType`  | string | Yes      | Event type identifier (e.g., `page_view`, `purchase`, `cart_add`) |
| `customerId` | string | No       | Customer identifier                                               |
| `sessionId`  | string | No       | Session identifier                                                |
| `timestamp`  | string | No       | ISO 8601 timestamp (defaults to now)                              |
| `properties` | object | No       | Arbitrary event properties                                        |

### Request Body — Batch

Send an array of event objects (max 100 per batch).

### Example — Single Event

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "eventType": "purchase",
    "customerId": "C-1234",
    "properties": {
      "product_id": "SKU-789",
      "amount": 49.99
    }
  }'
```

### Example — Batch

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '[
    { "eventType": "page_view", "customerId": "C-1234", "properties": { "page": "/products" } },
    { "eventType": "cart_add", "customerId": "C-1234", "properties": { "sku": "SKU-789" } }
  ]'
```

### Response (202)

```json theme={null}
{
  "accepted": 2,
  "results": [
    { "eventType": "page_view", "streamId": "evt_abc123", "triggersEvaluated": true },
    { "eventType": "cart_add", "streamId": "evt_def456", "triggersEvaluated": true }
  ]
}
```

<Tip>
  Events are automatically evaluated against active [Trigger Rules](/api-reference/triggers). If a trigger's conditions match, it fires its configured action (e.g., journey enrollment, webhook).
</Tip>