Skip to content

Area: Developers

POST

Search products as the shopper types

Path
/searchAsYouType/{accessToken}
Auth
Access token · browser or app
POST
/searchAsYouType/{accessToken}
curl --request POST \
--url https://releva.ai/api/v0/searchAsYouType/YOUR_ACCESS_TOKEN \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "search": "shirt", "filterBy": [ { "key": "Categories", "type": "string", "value": "Men/Shirts" } ], "context": { "page": { "locale": "en", "url": "https://demo-store.example.com/search" }, "profile": { "id": "demo-device-sayt-1" } } }'

Returns the ranked products, the facets and the match count for what a shopper has typed, using the domain’s Search As You Type settings (Personalization › Search As You Type): number of products, filters, blocked words, synonyms, description matching and, if set, the product feed that personalizes the ranking.

Only available products in context.page.locale (default: the domain’s locale) are searched. Product URLs carry rlv_aid, rlv_apid, rlv_apos (and rlv_pfid) so the Releva SDK can attribute the click; keep them.

When context.profile.id or context.deviceId is sent, one autocompleteInteraction event is recorded for the returned products. If context.profile.email or context.profile.phoneNumber is sent instead, that profile is looked up or created.

The access token is public (the browser SDK uses it). Send it as the last path segment, or as authorization: Bearer <accessToken> (the header wins; the path segment must still be present). The SDK sends the same body form-encoded as formPayload (base64 of the URI-encoded JSON).

accessToken
required
string format: uuid

The domain’s access token. Required in the path even when the authorization header is sent (the header then wins).

Example

YOUR_ACCESS_TOKEN
object
search
required

What the shopper typed. An empty string matches every available product.

string
filterBy

Selected facets. Omitted is the same as an empty array.

Array<object>
object
key
required

Categories for the category facet, otherwise a product custom-field key such as brand.

string
type
required

Custom-field type (string, numeric or date). Required, but ignored for Categories.

string
value
required

A filters[].options[].value from a previous response (for categories, the full path such as Men/Shirts).

string
context
required

Who is searching and on which page. Keys other than those listed are accepted.

object
profile
object
id

Releva profile id (from the push response). Used for personalized ranking and to record the interaction.

string
email

Legacy identification. The profile is looked up or created.

string
phoneNumber

Legacy identification, normalised with the domain country’s dialling code. The profile is looked up or created.

string
key
additional properties
any
deviceId

Browser device id (the SDK’s rlv_p cookie). Used when profile.id is missing.

string
profileId

Old SDKs. Treated as deviceId when deviceId is missing.

string
mode

Preview mode. debug, layout-edit and search-edit get results even when Search As You Type is switched off.

string
group

A/B test group as sent by the SDK.

string
page
object
locale

Catalog language to search (ISO 639-1, such as en). Defaults to the domain’s locale.

string
market

Shopify market handle. Products of that market and products without a market match.

string
url

Page URL, stored on the interaction event.

string
key
additional properties
any
key
additional properties
any

Example

{
"search": "shirt",
"filterBy": [
{
"key": "Categories",
"type": "string",
"value": "Men/Shirts"
}
],
"context": {
"page": {
"locale": "en",
"url": "https://demo-store.example.com/search"
},
"profile": {
"id": "demo-device-sayt-1"
}
}
}

Matching products and facets.

Media typeapplication/json
object
products
required

At most the configured number of products to show.

Array<object>
object
id
string
name
string
sku
string
locale
string
currency
string
listPrice
number
price

Current price (after discount).

number
discountPercent
number
categories
Array<string>
imageUrl
string
url

Product URL with rlv_aid=1, rlv_apid, rlv_apos and, when a product feed ranked it, rlv_pfid.

string
custom

Product custom fields by type.

object
string
Array<object>
object
key
string
values
Array
numeric
Array<object>
object
key
string
values
Array
date
Array<object>
object
key
string
values
Array
variantId
string
variants
Array<object>
object
variantId
string
optionValues
Array<object>
object
name
string
value
string
imageUrl
string
available
boolean
matchedVariant

Present when a word of the query names a colour one of the variants has.

object
variantId
string
optionValues
Array<object>
object
name
string
value
string
imageUrl
string
available
boolean
selectedVariant

Present when the selected facets identify a variant; use it to deep-link.

object
variantId
string
optionValues
Array<object>
object
name
string
value
string
imageUrl
string
available
boolean
filters
required

Configured facets that have at least one option for this query.

Array<object>
object
key

Categories or the custom-field key.

string
type
string
title

Facet title set in the admin.

string
options

Up to 5 most frequent values among the top 100 matches.

Array<object>
object
value

Value to send back in filterBy. For categories

string
label

Text to show. For categories

string
selected
boolean
total
required

Number of matching products (not capped by the number returned).

integer
query
required

The search value as sent, for a “View all results” link.

string

Example

{
"products": [
{
"id": "DEMO-1001",
"name": "Linen Summer Shirt",
"locale": "en",
"currency": "EUR",
"listPrice": 39.9,
"sku": "DEMO-1001-M",
"categories": [
"Men/Shirts",
"Summer"
],
"url": "https://demo-store.example.com/products/linen-summer-shirt?rlv_aid=1&rlv_apid=DEMO-1001&rlv_apos=0",
"imageUrl": "https://demo-store.example.com/images/linen-summer-shirt.jpg",
"custom": {
"string": [
{
"key": "brand",
"values": [
"Demo Basics"
]
},
{
"key": "color",
"values": [
"white",
"sand"
]
}
],
"numeric": [],
"date": []
},
"price": 39.9,
"discountPercent": 0,
"variants": [
{
"variantId": "DEMO-1001",
"optionValues": [],
"available": true
}
]
}
],
"filters": [
{
"key": "Categories",
"type": "string",
"title": "Category",
"options": [
{
"value": "Men/Shirts",
"label": "Shirts",
"selected": false
},
{
"value": "Summer",
"label": "Summer",
"selected": false
}
]
},
{
"key": "brand",
"type": "string",
"title": "Brand",
"options": [
{
"value": "Demo Basics",
"label": "Demo Basics",
"selected": false
}
]
}
],
"total": 1,
"query": "shirt"
}

Authentication or validation error, or Search As You Type is switched off.

Media typeapplication/json
object
message
required

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

string

Examples

{
"message": "Search As You Type functionality is disabled!"
}

The domain is disabled, or value delivery is paused because usage exceeded the plan limit.

Media typeapplication/json
object
message
required

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

string

Examples

{
"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. Also returned when Search As You Type has never been set up for the domain.

Media typeapplication/json
object
message
required

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

string

Example

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