Skip to content

Area: Developers

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.

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.

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.

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.

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.

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"]
}
]
}'

202 Accepted with the body {}. The event is usually readable within seconds. Read events returns its filter as a JSON string.

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.
  • Body size: 800 KB per request.
  • At most the first 10 products of each event are stored.
  • Rate limits: none.