# Send search events

> POST /api/v0/search: record a search or filtered listing from your backend in a shopper's history, with the filter grammar, a working curl, responses, errors and limits.

`POST /api/v0/search` records searches and filtered listings that ran on your backend. Each event is stored with the action `search` on the shopper’s profile.

## When to use it

Use it when a search or filtered listing runs on your backend and you want it in the shopper’s history. For example, a shopper searches for computers and adds filters for brand, RAM, processor and GPU. Searches on your site are already tracked by the SDK when the page push carries `page.query` and `page.filter`: see the [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/).

## Authentication

Send your shop’s **Secret Key** as a bearer token: `authorization: Bearer $RELEVA_SECRET_KEY`. Find it under **Settings › Shop & Integration** ([Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The error messages are in [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#authentication).

## Request

`POST https://releva.ai/api/v0/search` with `content-type: application/json` and a body `{ "events": [ ... ] }` that holds at least one event.

| Field       | Type             | Required | Notes                                                                                                                          |
| ----------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `email`     | string           | yes      | The only identifier this endpoint accepts.                                                                                     |
| `locale`    | string           | no       | ISO-639-1 code (`en`). If you support several languages or currencies, set it to the current locale.                           |
| `companyId` | string           | no       |                                                                                                                                |
| `timestamp` | string           | no       | ISO-8601 with seconds and a zone.                                                                                              |
| `tags`      | array of strings | no       |                                                                                                                                |
| `custom`    | object           | no       | `string`, `numeric` and `date` lists of `{ key, values }`.                                                                     |
| `products`  | array of objects | no       | The results, `{ "id": "..." }` only. The first 10 are stored.                                                                  |
| `filter`    | object           | no       | The filter used in this search. If the shopper ran a full-text search, the text constraints are part of the filter. See below. |

There is no field for the search text: `query` is rejected as an unknown key.

### The filter

`filter` is either a group or a condition:

* **Group**: `{ "operator": "and" | "or", "nested": [ ... ] }`. With `and`, every condition in `nested` must be true for a product to match; with `or`, one is enough. `nested` holds conditions, or inner groups with their own `operator`.

* **Condition**: `{ "key", "operator", "action", "value", "weight" }`:

  * `key`: a product field (`price`, `categories`) or `custom.<string|numeric|date>.<key>`.
  * `operator`: how `value` is compared with the product field: `eq` (equal to), `lt` (less than), `gt` (greater than), `lte` (less than or equal to), `gte` (greater than or equal to). Also accepted: `ex`, `gt,lt`, `gt,lte`, `gte,lt` and `gte,lte`.
  * `action`: what to do with matching products: `include` (only these), `exclude` (not these), `boost` (to the top) or `bury` (to the bottom).
  * `value`: always a string (`"50"`, not `50`).
  * `weight`: optional integer, 1 or more. Used only with `boost` or `bury`: when you have several, they are ordered by weight.

Releva stores the filter with the event; this endpoint does not run it.

```plaintext
curl -X POST 'https://releva.ai/api/v0/search' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "events": [
      {
        "email": "maria@example.com",
        "locale": "en",
        "timestamp": "2026-10-21T09:30:00Z",
        "products": [{ "id": "DEMO-1001" }, { "id": "DEMO-1002" }],
        "filter": {
          "operator": "and",
          "nested": [
            { "key": "categories", "operator": "eq", "action": "include", "value": "Summer" },
            {
              "operator": "or",
              "nested": [
                { "key": "custom.string.color", "operator": "eq", "action": "include", "value": "white" },
                { "key": "custom.string.color", "operator": "eq", "action": "include", "value": "sand" }
              ]
            },
            { "key": "price", "operator": "gte", "action": "include", "value": "20" },
            { "key": "price", "operator": "lte", "action": "include", "value": "50" },
            { "key": "custom.numeric.size", "operator": "gte", "action": "include", "value": "38" }
          ]
        },
        "custom": {
          "string": [{ "key": "source", "values": ["category-page"] }]
        },
        "tags": ["view"]
      }
    ]
  }'
```

## Response

`202 Accepted` with the body `{}`. The event is usually readable within seconds. [Read events](https://releva.ai/documentation/reference/events/read-events/) returns its `filter` as a JSON string.

## Errors

Errors have one shape, `{ "message": "..." }`. Filter errors name the field without its path.

| Status | When                          | Message                                                                                    |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed         | See [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#authentication) |
| `400`  | Missing `email`               | `The 'events[0].email' field is required.`                                                 |
| `400`  | `phoneNumber` sent            | `The object 'events[0]' contains forbidden keys: 'phoneNumber'.`                           |
| `400`  | `query` sent                  | `The object 'events[0]' contains forbidden keys: 'query'.`                                 |
| `400`  | `operator: "between"`         | `The 'operator' field does not match any of the allowed values.`                           |
| `400`  | `nested` is not an array      | `The 'nested' field must be an array.`                                                     |
| `400`  | `value: 50` (a number)        | `The 'value' field must be a string.`                                                      |
| `402`  | Your shop is disabled         | `Domain is disabled. Please reach out to support@releva.ai to enable it.`                  |
| `413`  | Body larger than 800 KB       | `request entity too large`                                                                 |
| `500`  | Unexpected error; retry later | `An internal error occurred.`                                                              |

## Limits

* Body size: 800 KB per request.
* At most the first 10 products of each event are stored.
* Rate limits: none.

## Next steps

* [How Search As You Type works](https://releva.ai/documentation/learn/search-as-you-type/how-search-as-you-type-works/): See how searches on your site are tracked and answered.
* [Read events](https://releva.ai/documentation/reference/events/read-events/): Fetch the stored search events, with their filters.
* [Events API overview](https://releva.ai/documentation/reference/events/overview/): Read the authentication, request format and error rules shared by all events calls.