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

# Browser Events API — POST /ct

> Reference for the browser event collection endpoint. Used by the Scanova Browser SDK to send page views, clicks, and custom events from user browsers.

The `/ct` endpoint receives browser events sent by the Scanova Browser SDK. In most cases you do not call this endpoint directly — the SDK handles it. This page documents the request format for custom integrations or debugging.

**Base URL:** `https://t.scanova.io`

## Endpoint

```
POST https://t.scanova.io/ct
```

No authentication header is required. Requests are validated by checking the `Origin` or `Referer` header against the site's **Allowed Domains** list.

## Request

**Headers:**

```http theme={null}
Content-Type: application/json
Origin: https://yoursite.com
```

**Body:**

```json theme={null}
{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8",
  "site_id": "YOUR_SITE_ID",
  "event_type": "cta_click",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "web_session_id": "2d0c328a-01d0-4010-85f4-f327130d1bd4",
  "visitor_id": "363fe851-7d8f-4090-902f-0f5a462829f5",
  "page_url": "https://yoursite.com/pricing",
  "referrer": "https://yoursite.com/",
  "timestamp": "2026-05-13T10:00:00.000Z",
  "device": {
    "user_agent": "Mozilla/5.0 ...",
    "screen_width": 1440,
    "screen_height": 900,
    "language": "en-US"
  },
  "metadata": {
    "button_text": "Start Free Trial",
    "section": "pricing"
  }
}
```

## Fields

| Field             | Type        | Required | Description                                  |
| ----------------- | ----------- | -------- | -------------------------------------------- |
| `site_id`         | string      | Yes      | Tracking site ID                             |
| `event_type`      | string      | Yes      | Event name in snake\_case                    |
| `event_id`        | UUID string | No       | Deduplication ID. Auto-generated if omitted. |
| `scan_session_id` | UUID string | No       | QR scan attribution ID                       |
| `web_session_id`  | UUID string | No       | Browser session ID (30-min timeout)          |
| `visitor_id`      | UUID string | No       | Persistent visitor ID (1-year cookie)        |
| `page_url`        | string      | No       | Current page URL                             |
| `referrer`        | string      | No       | Referring URL                                |
| `timestamp`       | ISO 8601    | No       | Event time. Defaults to receipt time.        |
| `device`          | object      | No       | User-agent, screen dimensions, language      |
| `metadata`        | object      | No       | Custom data. Max 10 KB, depth 5.             |
| `consent`         | string      | No       | `granted`, `denied`, or `pending`            |

## Response

**Success (`200`):**

```json theme={null}
{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8"
}
```

**Error responses:**

| Status | Cause                                                        |
| ------ | ------------------------------------------------------------ |
| `400`  | Missing required field or invalid `site_id`                  |
| `403`  | Request `Origin`/`Referer` not in the site's Allowed Domains |
| `413`  | Payload exceeds size limit                                   |
| `422`  | Field validation error                                       |
| `429`  | Rate limit exceeded (100 requests/min per IP)                |

## CORS

The `/ct` endpoint supports CORS. Browser requests from allowed domains are permitted with:

```
Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: POST, OPTIONS
```

Preflight (`OPTIONS`) requests return `204` with the appropriate CORS headers.

## Batch endpoint

To send multiple browser events in a single request:

```
POST https://t.scanova.io/collect/batch
```

Request body wraps an array:

```json theme={null}
{
  "events": [
    { "site_id": "...", "event_type": "pageview", ... },
    { "site_id": "...", "event_type": "scroll", "metadata": { "scroll_depth": 25 } }
  ]
}
```

Up to 100 events per batch request.