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

# Event reference

> Request shape, event names, data types, and response outcomes.

An envelope has `version: 1`, one required `tag_id`, optional `test_mode`, and between one and 1,000 `events`. Unknown fields are rejected.

Each event needs a stable `event_id`, an `event_name`, and `timestamp_ms`. The timestamp is Unix milliseconds and must be no more than seven days old or ten minutes in the future. `web` events also require `source_url`.

Use these canonical event names: `page_viewed`, `contents_viewed`, `items_added`, `checkout_started`, `order_created`, `lead_created`, `registration_completed`, `appointment_scheduled`, `subscription_created`, `trial_started`, `app_installed`, `app_opened`, and `custom`.

Common aliases such as `purchase`, `add_to_cart`, `page_view`, and `signup` are normalized. `custom` requires `custom_event_name`. `app_installed` and `app_opened` require `action_source: "mobile_app"` and `data.type: "customer_action"`.

| Data type | Use for |
| - | - |
| `contents` | Page, product, cart, checkout, and order events. Supports integer minor-unit `amount`, ISO currency, and `contents`. |
| `customer_action` | Leads, registrations, appointments, and app lifecycle events. |
| `plan_enrollment` | Trial and subscription events. Supports `plan_id`, amount, currency, and contents. |
| `custom` | Custom events. Supports the same commerce fields plus arbitrary JSON properties. |

Use the same `event_id` for browser and server copies of a conversion. Thrad deduplicates per `tag_id` and `event_id`; a repeat is returned as `duplicate` instead of creating another canonical event.


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