Event Ingestion API

The Event Ingestion API accepts typed customer events, publishes them to the internal event stream, and evaluates them against active trigger rules in real time. When a trigger matches, its configured action is dispatched automatically.

This endpoint is separate from the batch Events API. Use this for real-time, single-event ingestion from mobile apps, websites, and backend services.

Base Path

/api/v1/events/ingest

POST /api/v1/events/ingest

Ingest a single customer event for real-time processing. Roles: Any authenticated user (no role check — only requires valid tenant).

Request Body

Field	Type	Required	Description
`type`	string	Yes	Event type. One of: `purchase`, `cart_abandon`, `page_view`, `app_open`, `support_call`
`customerId`	string	Yes	Customer identifier
`data`	object	No	Arbitrary event properties (e.g., product ID, amount, page URL)
`channel`	string	No	Source channel (e.g., `web`, `mobile`, `pos`)
`timestamp`	string	No	ISO 8601 timestamp. Defaults to server time if omitted

Event Types

Type	Description	Internal Mapping
`purchase`	Customer completed a purchase	Also evaluates triggers for `outcome.recorded`
`cart_abandon`	Customer abandoned their cart	Also evaluates triggers for `customer.updated`
`page_view`	Customer viewed a page	Behavioral event only
`app_open`	Customer opened the mobile app	Behavioral event only
`support_call`	Customer contacted support	Also evaluates triggers for `customer.updated`

Each event type is mapped to one or more internal trigger event types. This means a single purchase event can fire both purchase-specific triggers and broader outcome.recorded triggers.

Response `200`

{
  "ingested": true,
  "eventType": "purchase",
  "customerId": "CUST-001",
  "streamId": "evt_abc123def",
  "triggersMatched": [
    {
      "triggerId": "tr_001",
      "actionType": "recommend"
    },
    {
      "triggerId": "tr_002",
      "actionType": "journey_enroll"
    }
  ],
  "actionsDispatched": [
    {
      "triggerId": "tr_001",
      "actionType": "recommend",
      "config": { "decisionFlowId": "df_upsell", "channel": "push" }
    },
    {
      "triggerId": "tr_002",
      "actionType": "journey_enroll",
      "config": { "journeyId": "j_post_purchase" }
    }
  ]
}

Response Fields

Field	Type	Description
`ingested`	boolean	Always `true` on success
`eventType`	string	The event type that was ingested
`customerId`	string	The customer identifier
`streamId`	string or null	Event stream ID (null if stream publish failed — event is still processed)
`triggersMatched`	array	Trigger rules that matched this event
`actionsDispatched`	array	Actions that were successfully dispatched
`actionErrors`	array	(Only present if errors occurred) Actions that failed to dispatch

Example

# Purchase event with metadata
curl -X POST https://playground.kaireonai.com/api/v1/events/ingest \
  -H "X-Tenant-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "type": "purchase",
    "customerId": "CUST-001",
    "channel": "pos",
    "data": {
      "orderId": "ORD-789",
      "amount": 49.99,
      "productId": "SKU-456",
      "storeId": "STORE-01"
    }
  }'

# Cart abandonment from web
curl -X POST https://playground.kaireonai.com/api/v1/events/ingest \
  -H "X-Tenant-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cart_abandon",
    "customerId": "CUST-002",
    "channel": "web",
    "data": {
      "cartValue": 129.99,
      "itemCount": 3,
      "abandonedUrl": "/checkout"
    }
  }'

Processing Pipeline

When an event is ingested, the following happens in order:

Validation — The request body is validated against the Zod schema. Invalid events return a 400.
Event stream publish — The event is published to the internal event bus. If the stream is unavailable, processing continues (non-critical).
Trigger evaluation — Active trigger rules are loaded and evaluated against the event. Each matching trigger’s action is dispatched.
Response — The API returns the ingestion result with matched triggers and dispatched actions.

Event stream publish failures are non-critical and will not cause the API to return an error. The event is still evaluated against triggers. Check the streamId field — a null value indicates the stream publish failed.

Cross-Channel Triggers

Event ingestion powers cross-channel workflows. For example:

Event Source	Trigger Action	Result
POS `purchase`	`recommend` via push channel	Customer gets a push notification with a related offer
Web `cart_abandon`	`journey_enroll`	Customer enters a 3-step email recovery journey
App `app_open`	`recommend` via in-app channel	Customer sees personalized offers on the home screen
Support `support_call`	Webhook notification	CRM system is updated with the interaction

Error Codes

Status	Code	Description
`400`	Bad Request	Invalid event type or missing `customerId`
`401`	Unauthorized	Missing or invalid authentication
`500`	Server Error	Internal processing error

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Event Ingestion API

Base Path

POST /api/v1/events/ingest

Request Body

Event Types

Response `200`

Response Fields

Example

Processing Pipeline

Cross-Channel Triggers

Error Codes

See Also

​Base Path

​POST /api/v1/events/ingest

​Request Body

​Event Types

​Response 200

​Response Fields

​Example

​Processing Pipeline

​Cross-Channel Triggers

​Error Codes

​See Also

Base Path

POST /api/v1/events/ingest

Request Body

Event Types

Response `200`

Response Fields

Example

Processing Pipeline

Cross-Channel Triggers

Error Codes

See Also