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

# Events API

> Request and response reference for POST /v0/events: browser and game events with the publishable key, and server events with the secret key.

One endpoint, `POST /v0/events`, takes website (`web`), game (`app`) and server (`server`) events. A batch is either all server events or has no server events.

## Browser events

```http theme={null}
POST /v0/events
X-Publishable-Key: YOUR_PUBLISHABLE_KEY
Content-Type: application/json

{ "events": [ Event, ... ] }
```

The [Web SDK](https://docs.manalens.dev/sdks/web.md) calls this endpoint for you. A batch has 1 to 50 events. For game builds with `channel: 'app'` and `context.app`, see [app events](https://docs.manalens.dev/sdks/app-events.md).

### Event fields

| Field | Rule |
| - | - |
| `type` | `page`, `track` or `identify` |
| `event` | Required for `track`, forbidden for `identify`. At most 128 characters. |
| `message_id` | A UUID |
| `channel` | `web` (with `context.page`) or `app` (with `context.app` and no page) |
| `version` | The SDK envelope version |
| `original_timestamp` | ISO 8601 date and time |
| `anonymous_id` | A UUID. Absent before consent in consent mode. |
| `session_id` | Required with an `anonymous_id`, and never equal to it. Letters, digits and `_ . : -`, at most 64 characters. Absent before consent, with the `anonymous_id`. See [the session ID contract](#the-session-id-contract). |
| `user_id` | Optional, at most 255 characters. Required for `identify`. |
| `properties` | A flat object of string (at most 1024 characters), number, boolean or `null` values |
| `traits` | `identify` only. Same value rules; keys up to 100 characters. |
| `context.page` | `path`, `title` and `url`. The URL must be on the project domain, and `path` must match it. |
| `context.referrer` | The document referrer. Only an external origin is kept. |
| `context.app` | Optional on a web event: `platform`, `storefront`, `app_version`, `build`, `engine`, for a browser or Electron game. See [Browser and Electron games](https://docs.manalens.dev/sdks/app-events.md#browser-and-electron-games). An app object that is not valid refuses the event. |
| `context.locale` | Optional browser locale |
| `context` campaign fields | The allowlisted UTM, referral and click ID fields in [what we collect](https://docs.manalens.dev/data/what-we-collect.md#campaign-and-ad-parameters) |

### Checks

* `X-Publishable-Key` must be the publishable key of a project. A secret key or an API key in this header gets `401`.
* Send no `Authorization` header.
* A browser `Origin` must be the project domain or one of its subdomains. A request with no `Origin` (for example from a server proxy) is allowed; the page URL check still applies.
* Unknown fields are rejected.

### The session ID contract

Reports count [sessions](https://docs.manalens.dev/data/metrics.md#sessions) from the `session_id` of each event. So a website or game event must follow three rules:

* An event with an `anonymous_id` has a `session_id`.
* The `session_id` is not the `anonymous_id`. Make a new ID for each session: start a new session after 30 minutes without events, and when the session is 24 hours old.
* An event before consent has no `anonymous_id` and no `session_id`. It is accepted and stored, and it is in no session.

A batch with an event that breaks a rule gets `400` `INVALID_EVENT`, and no event of the batch is accepted. The response lists each refused event (at most 50) with its position in the batch, its `message_id` and a reason code:

```json theme={null}
{
  "error": {
    "code": "INVALID_EVENT",
    "message": "1 of 2 events break the session ID contract. No event of the batch was accepted",
    "refused": [
      { "index": 1, "message_id": "0b7c0a6e-52f8-4f43-8f0b-5f1f6f0f2a11", "code": "SESSION_ID_REQUIRED", "message": "An event with an anonymous_id needs a session_id. Update the SDK, or send the session ID of the client" }
    ]
  }
}
```

| Reason code | Cause |
| - | - |
| `SESSION_ID_REQUIRED` | The event has an `anonymous_id` and no `session_id` |
| `SESSION_ID_IS_ANONYMOUS_ID` | The `session_id` is equal to the `anonymous_id` |
| `SESSION_ID_WITHOUT_ANONYMOUS_ID` | The event has a `session_id` and no `anonymous_id` |

Do not send a refused batch again without a change: it is refused again. The SDKs drop it and log the reason. The contract does not apply to [server events](#server-events): a server event with no `session_id` is valid.

### Responses

| Status | Body |
| - | - |
| `202` | `{ "accepted": 3 }` |
| `400` | `INVALID_EVENT`: a field is not valid. With `refused`, the batch breaks [the session ID contract](#the-session-id-contract). |
| `401` | `UNAUTHORIZED`: missing or invalid publishable key, a secret key or an API key in `X-Publishable-Key`, or both headers sent |
| `403` | `FORBIDDEN`: origin or page domain does not match the project. `WORKSPACE_SUSPENDED`: the workspace does not accept events. `PUBLISHABLE_KEY_REQUIRED`: web or app events sent with the secret key. |
| `429` | `RATE_LIMITED`: the project sent too many events this minute. Retry after `Retry-After`. |

## Server events

```http theme={null}
POST /v0/events
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

{ "events": [ ServerEvent, ... ] }
```

Send the [secret key](https://docs.manalens.dev/api/authentication.md#secret-key) from your backend only. A batch has 1 to 100 events, and the body is at most 256 KB. See [server events](https://docs.manalens.dev/sdks/server.md) for setup and examples.

### Server event fields

| Field | Rule |
| - | - |
| `channel` | `server` |
| `type` | `track` or `identify` |
| `event` | Required for `track`, forbidden for `identify`. At most 128 characters. |
| `anonymous_id` | Optional UUID. Forward the ID of the browser or game to join the event to that visitor. |
| `user_id` | Optional, at most 255 characters. Required for `identify`. |
| | At least one of `anonymous_id` or `user_id` is required. `user_id` alone is enough. |
| `session_id` | Optional. The session ID of the client (`[A-Za-z0-9_.:-]`, at most 64), sent with its `anonymous_id`: the event is then in that session. Without it, the event joins a session of the same `anonymous_id` by time. See [send the client's session ID](https://docs.manalens.dev/sdks/server.md#session-id-of-the-client). |
| `properties` | A flat object of string (at most 1024 characters), number, boolean or `null` values |
| `traits` | `identify` only, same value rules. A work `email` also sets `company_domain`. |
| `message_id` | Optional UUID for retries. Generated when absent. Reports count each `message_id` once. |
| `original_timestamp` | Optional ISO 8601. Defaults to the time received. At most 5 minutes in the future. Past times are accepted for backfills. |
| `context.ip` | Optional IPv4 or IPv6 address of the player. Used only for an in-memory country lookup. Never stored or logged. |
| `context.user_agent` | Optional user agent of the player. Parsed to device, OS and browser. A bot user agent gets device `bot` and is excluded from reports. Never stored. |
| `context.country` | Optional ISO 3166-1 alpha-2 code. Wins over the country from `context.ip`. Defaults to `ZZ` (unknown). |
| `context.device` | Optional `desktop`, `mobile` or `tablet`. Wins over the value from `context.user_agent`. |
| `context.os`, `context.browser` | Optional. Win over the values from `context.user_agent`. |
| `context.locale` | Optional locale |
| `context.page` | Optional `path`, `title`, `url` |
| `context.app` | Optional, the same object as on [app events](https://docs.manalens.dev/sdks/app-events.md#the-app-context). With a native platform, the OS and device come from the platform. |
| `context.library_name`, `context.library_version` | Optional name and version of your server code |

Unknown fields are rejected. The collector does not use the request IP or the request user agent for server events.

### Server event checks

* `Authorization: Bearer` must be the secret key of a project. Send no `X-Publishable-Key` header.
* The request must not have an `Origin` header.
* Every event in the batch has `channel: 'server'`.

### Server event responses

| Status | Body |
| - | - |
| `202` | `{ "accepted": 2 }` |
| `400` | `INVALID_EVENT`, with up to five validation `issues`. `MIXED_CHANNELS`: the batch mixes server events with web or app events. |
| `401` | `UNAUTHORIZED`: missing or unknown secret key, a publishable key in `Authorization`, or both headers sent |
| `403` | `SECRET_KEY_FROM_BROWSER`: the request has an `Origin` header |
| `403` | `SECRET_KEY_REQUIRED`: server events sent with the publishable key |
| `403` | `WORKSPACE_SUSPENDED`: the workspace does not accept events |
| `413` | `TOO_LARGE`: the batch exceeds 256 KB |
| `429` | `RATE_LIMITED`: the project sent too many server events this minute. Retry after `Retry-After`. |

### Example

```bash theme={null}
curl -X POST https://api.your-domain.com/v0/events \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events":[{"channel":"server","type":"track","event":"purchase_completed","user_id":"player_123","properties":{"sku":"dlc_1"},"context":{"ip":"203.0.113.7","user_agent":"Mozilla/5.0 ..."}}]}'
```

See [errors](https://docs.manalens.dev/api/errors.md) for every code, and [idempotency](https://docs.manalens.dev/api/idempotency.md) for safe retries.


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