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

# Events

> POST /api/sdk/events -- Send behavioral tracking events.

## Endpoint

```
POST /api/sdk/events
```

Send a batch of behavioral events (page views, clicks, form submissions, etc.) for tracking and analysis. Events are used by the AI's awareness system to understand user behavior patterns.

## Authentication

Requires your publishable widget key in the `Authorization` header:

```
Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx
```

## Request Body

**events** `array` *required*

Array of event objects (max 100 per batch).

**user\_id** `string`

The user's external ID. If provided, events are linked to the user record. The user is automatically upserted (created if new, updated with a fresh `last_seen` timestamp if existing).

**session\_id** `string`

Session identifier to group events.

### Event Object

Each event in the array should have:

**event\_type** `string` *required*

The type of event (e.g., `"click"`, `"page_view"`, `"form_submit"`, `"error"`).

**element\_selector** `string`

CSS selector of the element involved (for click events, etc.).

**page\_url** `string`

The URL where the event occurred.

**metadata** `object`

Additional data about the event. Max 10,000 bytes per event.

## Example

```bash theme={null}
curl -X POST https://api.haloagents.ai/api/sdk/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "session_id": "sess_abc123",
    "events": [
      {
        "event_type": "page_view",
        "page_url": "/settings/integrations",
        "metadata": { "referrer": "/dashboard" }
      },
      {
        "event_type": "click",
        "element_selector": "#connect-stripe-btn",
        "page_url": "/settings/integrations"
      }
    ]
  }'
```

**Response:**

```json theme={null}
{
  "success": true
}
```

## Notes

* Events are collected automatically by the built-in tracker. You typically don't need to call this endpoint directly unless building a custom integration.
* The user record is created or updated (last seen timestamp) when `user_id` is provided.
* Field lengths are sanitized: `event_type` is capped at 100 chars, `element_selector` at 500 chars, `page_url` at 2,000 chars, and `session_id` at 200 chars.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.