> ## Documentation Index
> Fetch the complete documentation index at: https://client-integrations-api-dev.sequen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Engagement Events

> Sending real-time user engagement events to Sequen.

# CDS - Engagement Events

Send real-time user interaction data to Sequen's Large Event Models (LEMs) via the Engagement Events endpoint. This data is crucial for training models and enabling in-session personalization.

## Endpoint

```
POST /catalog/engagement
```

## Request Body

The request body should be a JSON object representing a single event, OR a JSON array containing multiple event objects for bulk submission.

**Single Event:**

| Field        | Type   | Required | Description                                                                 |
| :----------- | :----- | :------- | :-------------------------------------------------------------------------- |
| `type`       | String | Yes      | Type of event (e.g., `view`, `click`, `purchase`, `add_to_cart`, `search`). |
| `userId`     | String | Yes      | Unique identifier for the user performing the action.                       |
| `sessionId`  | String | Yes      | Unique identifier for the user's current session.                           |
| `timestamp`  | String | Yes      | ISO 8601 formatted timestamp of when the event occurred (UTC recommended).  |
| `properties` | Object | Yes      | A JSON object containing contextual details about the event.                |

**Bulk Events:**

Send a JSON array where each element is a complete event object as described above.

```json Bulk Request Structure theme={null}
[
  { "type": "...", "userId": "...", ... },
  { "type": "...", "userId": "...", ... },
  ...
]
```

### Properties Object

The `properties` object can contain any relevant key-value pairs. Include as much context as possible, even unstructured data. Examples:

* `item_id`: Identifier of the item involved (e.g., product SKU).
* `item_list_id`: Identifier for a list the item appeared in (e.g., category page, search results ID).
* `page_type`: Type of page where the event occurred (e.g., `product_detail`, `category`, `checkout`).
* `query`: The search query used (for `search` or `click` events from search).
* `order_id`: Identifier for a purchase event.
* `total_value`: Total value of an order.
* `currency`: Currency code (e.g., `USD`).
* Custom attributes: `color`, `size`, `category_path`, device information, etc.

## Example Requests

<Tabs>
  <Tab title="Single Event">
    <CodeBlock title="POST /cds/engagement (Single Event)">
      ```json Example Body theme={null}
      {
        "type": "add_to_cart",
        "userId": "user_f9b3d",
        "sessionId": "session_k2p0a",
        "timestamp": "2024-07-27T10:30:00Z",
        "properties": {
          "item_id": "SKU-12345-BLK-L",
          "page_type": "product_detail",
          "quantity": 1,
          "price": 59.99,
          "currency": "USD",
          "category_path": "Apparel > Tops > T-Shirts",
          "color": "Black",
          "size": "L"
        }
      }
      ```
    </CodeBlock>
  </Tab>

  <Tab title="Bulk Events">
    <CodeBlock title="POST /cds/engagement (Bulk Events)">
      ```json Example Body theme={null}
      [
        {
          "type": "view",
          "userId": "user_a1b2c",
          "sessionId": "session_x9y8z",
          "timestamp": "2024-07-28T11:00:00Z",
          "properties": {
            "item_id": "ITEM-001",
            "page_type": "product_detail"
          }
        },
        {
          "type": "add_to_cart",
          "userId": "user_a1b2c",
          "sessionId": "session_x9y8z",
          "timestamp": "2024-07-28T11:00:15Z",
          "properties": {
            "item_id": "ITEM-001",
            "quantity": 1,
            "price": 19.99,
            "currency": "USD"
          }
        },
        {
          "type": "view",
          "userId": "user_d3e4f",
          "sessionId": "session_w7v6u",
          "timestamp": "2024-07-28T11:01:00Z",
          "properties": {
            "page_type": "category",
            "category_path": "Electronics > Audio"
          }
        }
      ]
      ```
    </CodeBlock>
  </Tab>
</Tabs>

## Responses

* **`202 Accepted`**: The event was successfully received and queued for processing.
* **`400 Bad Request`**: The request body is malformed or missing required fields. The response body will contain details.
* **`401 Unauthorized`**: Invalid or missing API key.
* **`429 Too Many Requests`**: Rate limit exceeded.
* **`5xx Server Error`**: An internal error occurred.

<Info>
  Sending rich, timely event data is critical to Sequen's performance. Ensure you track all relevant user interactions.
</Info>