Send search events
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
Section titled “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.
Authentication
Section titled “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). The error messages are in Events API: Authentication.
Request
Section titled “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
Section titled “The filter”filter is either a group or a condition:
- Group:
{ "operator": "and" | "or", "nested": [ ... ] }. Withand, every condition innestedmust be true for a product to match; withor, one is enough.nestedholds conditions, or inner groups with their ownoperator. - Condition:
{ "key", "operator", "action", "value", "weight" }:key: a product field (price,categories) orcustom.<string|numeric|date>.<key>.operator: howvalueis 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,ltandgte,lte.action: what to do with matching products:include(only these),exclude(not these),boost(to the top) orbury(to the bottom).value: always a string ("50", not50).weight: optional integer, 1 or more. Used only withboostorbury: when you have several, they are ordered by weight.
Releva stores the filter with the event; this endpoint does not run it.
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
Section titled “Response”202 Accepted with the body {}. The event is usually readable within seconds. Read events returns its filter as a JSON string.
Errors
Section titled “Errors”Errors have one shape, { "message": "..." }. Filter errors name the field without its path.
| Status | When | Message |
|---|---|---|
400 |
Authentication failed | See Events API: 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
Section titled “Limits”- Body size: 800 KB per request.
- At most the first 10 products of each event are stored.
- Rate limits: none.