Skip to content

Area: Developers

POST

Send search events

Path
/search
Auth
Secret key · server only
POST
/search
curl --request POST \
--url https://releva.ai/api/v0/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "events": [ { "email": "maria@example.com", "locale": "en", "timestamp": "2026-10-21T09:30:00.000Z", "products": [ { "id": "DEMO-1001" }, { "id": "DEMO-1002" } ], "filter": { "operator": "and", "nested": [ { "key": "categories", "operator": "eq", "action": "include", "value": "Summer" }, { "key": "price", "operator": "lte", "action": "include", "value": "50" }, { "key": "custom.string.brand", "operator": "eq", "action": "boost", "value": "Demo Basics", "weight": 2 } ] }, "tags": [ "filter-panel" ], "custom": { "string": [ { "key": "sort", "values": [ "price-asc" ] } ] } } ] }'

Records searches performed on your backend as search events on the profile with the given email (created if missing). Only the first 10 products of each event are stored; they are enriched from the catalog. The search text cannot be sent (there is no query field). Asynchronous.

Media typeapplication/json
object
events
required
Array<object>
>= 1 items
object
email
required

The only accepted identifier.

string format: email
locale
string
/^[a-z]{2}$/
companyId
string
products

Results shown. Only the first 10 are stored.

Array<object>
object
id
required
string
filter
One of:
object
operator
required
string
Allowed values: and or
nested
required
Array<object> recursive
timestamp

ISO-8601 date-time with seconds and a timezone offset (Z, +0300 or +03:00), optional milliseconds.

string
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|[+-]\d{2}:?\d{2})$/
custom

Custom attributes, usable in segments.

object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required
Array<string>
tags
Array<string>

Example

{
"events": [
{
"email": "maria@example.com",
"locale": "en",
"timestamp": "2026-10-21T09:30:00.000Z",
"products": [
{
"id": "DEMO-1001"
},
{
"id": "DEMO-1002"
}
],
"filter": {
"operator": "and",
"nested": [
{
"key": "categories",
"operator": "eq",
"action": "include",
"value": "Summer"
},
{
"key": "price",
"operator": "lte",
"action": "include",
"value": "50"
},
{
"key": "custom.string.brand",
"operator": "eq",
"action": "boost",
"value": "Demo Basics",
"weight": 2
}
]
},
"tags": [
"filter-panel"
],
"custom": {
"string": [
{
"key": "sort",
"values": [
"price-asc"
]
}
]
}
}
]
}

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "The 'events[0].email' field is required."
}

The domain is disabled.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

Request body larger than 800 KB.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "request entity too large"
}

Unexpected server error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}