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

# Events

> Ingest user behavior events for analytics and personalized recommendations

## Authentication

All requests must include an API key via the `x-api-key` header or `key` query parameter.

```bash theme={null}
curl -X POST https://alana.shopping/api/v1/events \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{
    "events": [
      {
        "eventType": "detail-page-view",
        "visitorId": "visitor-123",
        "productId": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'
```

## Rate Limits

| Level            | Limit          | Window   |
| ---------------- | -------------- | -------- |
| Per API key      | 1,000 requests | 1 minute |
| Per API key + IP | 100 requests   | 1 minute |

## Event Types

| Event Type                | Required Fields                                  | Description                        |
| ------------------------- | ------------------------------------------------ | ---------------------------------- |
| `home-page-view`          | `visitorId`                                      | User viewed the home page          |
| `search`                  | `visitorId`, `query`                             | User performed a search            |
| `category-view`           | `visitorId`, `categoryPath`                      | User browsed a category page       |
| `detail-page-view`        | `visitorId`, `productId`                         | User viewed a product detail page  |
| `add-to-cart`             | `visitorId`, `productId`                         | User added a product to their cart |
| `shopping-cart-page-view` | `visitorId`                                      | User viewed their cart             |
| `purchase-complete`       | `visitorId`, `productIds`, `revenue`, `currency` | User completed purchase            |

## Request Format

Send a batch of up to 100 events in a single request.

```json theme={null}
{
  "events": [
    {
      "eventType": "search",
      "visitorId": "visitor-abc",
      "userId": "user-123",
      "query": "camiseta azul"
    },
    {
      "eventType": "detail-page-view",
      "visitorId": "visitor-abc",
      "productId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
```

### Common Fields

| Field       | Type   | Required | Description                                 |
| ----------- | ------ | -------- | ------------------------------------------- |
| `eventType` | string | Yes      | One of the 7 event types listed above       |
| `visitorId` | string | Yes      | Anonymous visitor identifier                |
| `userId`    | string | No       | Authenticated user ID (for personalization) |
| `metadata`  | object | No       | Additional context (free-form key/value)    |

## Response Format

```json theme={null}
{
  "status": "ok",
  "stored": 2,
  "errors": 0
}
```

| Field    | Type   | Description                             |
| -------- | ------ | --------------------------------------- |
| `status` | string | Always `"ok"` on success                |
| `stored` | number | Number of events successfully stored    |
| `errors` | number | Number of events that failed validation |