# Events API overview

> The events calls, one page each, and the authentication, request format, responses and limits they share.

The events API records and reads the events of one shop. Each call has its own page:

| Call                                                                                          | Endpoint                            | What it does                                                                    |
| --------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------- |
| [Send custom events](https://releva.ai/documentation/reference/events/send-custom-events/)                     | `POST /events`                      | Record events from your backend on a known customer                             |
| [Send search events](https://releva.ai/documentation/reference/events/send-search-events/)                     | `POST /search`                      | Record searches and filtered listings from your backend                         |
| [Read events](https://releva.ai/documentation/reference/events/read-events/)                                   | `GET /events`                       | Read the shop’s events, newest first, 10 per page                               |
| [Send events from the browser](https://releva.ai/documentation/reference/events/send-events-from-the-browser/) | `Releva.push(…, { events: [...] })` | Record events in the browser with the access token (`POST /push/{accessToken}`) |

The three server endpoints are under `https://releva.ai/api/v0` and use your secret key. Order status updates are `orderStatusChanged` events on `POST /events`: see [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/). For how these fit together, read [How events get into Releva](https://releva.ai/documentation/learn/events/how-events-get-into-releva/).

## When to use which

* [Send custom events](https://releva.ai/documentation/reference/events/send-custom-events/): the action happens outside the browser (POS, CRM, back office, quote forms, loyalty) or you want to attach it to a known customer by email, phone or your profile id.
* [Send search events](https://releva.ai/documentation/reference/events/send-search-events/): a search or filtered listing ran on your backend and you want it in the shopper’s history. Searches on your site are tracked by the SDK with `page.query` and `page.filter`.
* [Send events from the browser](https://releva.ai/documentation/reference/events/send-events-from-the-browser/): the action happens in the browser. Easiest to add, and it works for anonymous visitors.
* [Read events](https://releva.ai/documentation/reference/events/read-events/): you want the log in your own systems.

## Authentication

Send your shop’s secret key as a bearer token:

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

The key is a UUID and identifies the shop (domain). Find it in the Releva admin under **Settings › Shop & Integration**. The SDK path uses the public access token in the URL instead and needs no header.

Authentication failures answer **`400`**, not `401`:

| Problem                        | Message                                                                       |
| ------------------------------ | ----------------------------------------------------------------------------- |
| No `authorization` header      | `Authorization header is missing.`                                            |
| Header is not `Bearer <token>` | ``Authorization header is malformed. It should look like `Bearer <string>`.`` |
| Token is not a UUID            | `Authorization header contains an invalid Bearer token.`                      |
| No shop has this key           | `Domain with the provided secret key cannot be found.`                        |

A shop that has been switched off answers **`402`** with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

## Request format

* HTTPS only. Plain HTTP answers `400 {"message":"We do not support non-HTTPS requests."}`.
* Send JSON with `content-type: application/json`. With any other content type the body is not parsed and you get `400 {"message":"The '' field is required."}`.
* Bodies are limited to **800 KB**. Larger bodies answer `413 {"message":"request entity too large"}`. There is no maximum number of events per request other than that limit.
* Objects are validated strictly: a key that is not in the schema is rejected with `The object 'events[0]' contains forbidden keys: '<key>'.`
* Timestamps are ISO-8601 with seconds and a zone: `2026-10-21T09:15:00Z`, `2026-10-21T09:15:00.000Z` or `2026-10-21T12:15:00+0300`. A date without time is rejected. Values are stored in UTC.
* `locale` is a two-letter ISO-639-1 code (`en`, not `en-US`). `currency` is an ISO-4217 code (`EUR`).
* Custom fields use one shape everywhere: `"custom": { "string": [{ "key", "values": [..] }], "numeric": [..], "date": [..] }`. Each list is optional; value types must match the list.

## Responses

The three write paths answer **`202 Accepted`** with the body `{}` (the SDK push answers `200` with its normal personalization payload). Processing is asynchronous; events are usually readable within seconds. See [Writes are asynchronous](https://releva.ai/documentation/learn/events/how-events-get-into-releva/#writes-are-asynchronous).

Errors have one shape, with no code or field property:

```plaintext
{ "message": "The 'events[0].action' field is required." }
```

| Status        | When                                                                        |
| ------------- | --------------------------------------------------------------------------- |
| `202` / `200` | Accepted and queued                                                         |
| `400`         | Authentication failed, validation failed, or the body could not be parsed   |
| `402`         | The shop is disabled                                                        |
| `413`         | Body larger than 800 KB                                                     |
| `500`         | Unexpected error: `{"message":"An internal error occurred."}`. Retry later. |

## Limits

* Body size: 800 KB per request.
* Rate limits: none on the events endpoints.
* `GET /events` returns at most 10 events per call.
* `POST /search` stores at most the first 10 products of each event.

## Versioning

All events endpoints are under `/api/v0`. Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/). Unknown fields are rejected, so new fields are safe to add only after they appear in the reference.

## Next steps

* [Send custom events](https://releva.ai/documentation/reference/events/send-custom-events/): Start with the call that records events from your backend, with a field table and a working request.
* [How events get into Releva](https://releva.ai/documentation/learn/events/how-events-get-into-releva/): Learn how an event is attached to a profile, what a custom event can carry and where it is used.
* [Check that an event reached Releva](https://releva.ai/documentation/guides/events/check-that-an-event-reached-releva/): Read the raw event in the admin to confirm it was stored with the right data.