Search products as the shopper types
- Path
/searchAsYouType/{accessToken}- Auth
- Access token · browser or app
const url = 'https://releva.ai/api/v0/searchAsYouType/YOUR_ACCESS_TOKEN';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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"}}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The domain’s access token. Required in the path even when the authorization header is sent (the header then wins).
Example
YOUR_ACCESS_TOKENRequest Bodyrequired
Section titled “Request Bodyrequired”object
What the shopper typed. An empty string matches every available product.
Selected facets. Omitted is the same as an empty array.
object
Categories for the category facet, otherwise a product custom-field key such as brand.
Custom-field type (string, numeric or date). Required, but ignored for Categories.
A filters[].options[].value from a previous response (for categories, the full path such as Men/Shirts).
Who is searching and on which page. Keys other than those listed are accepted.
object
object
Releva profile id (from the push response). Used for personalized ranking and to record the interaction.
Legacy identification. The profile is looked up or created.
Legacy identification, normalised with the domain country’s dialling code. The profile is looked up or created.
Browser device id (the SDK’s rlv_p cookie). Used when profile.id is missing.
Old SDKs. Treated as deviceId when deviceId is missing.
Preview mode. debug, layout-edit and search-edit get results even when Search As You Type is switched off.
A/B test group as sent by the SDK.
object
Catalog language to search (ISO 639-1, such as en). Defaults to the domain’s locale.
Shopify market handle. Products of that market and products without a market match.
Page URL, stored on the interaction event.
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" } }}object
Base64(encodeURIComponent(JSON body)). What the browser SDK sends.
Example generated
formPayload=exampleResponses
Section titled “Responses”Matching products and facets.
object
At most the configured number of products to show.
object
Current price (after discount).
Product URL with rlv_aid=1, rlv_apid, rlv_apos and, when a product feed ranked it, rlv_pfid.
Product custom fields by type.
object
object
object
object
object
object
Present when a word of the query names a colour one of the variants has.
object
object
Present when the selected facets identify a variant; use it to deep-link.
object
object
Configured facets that have at least one option for this query.
object
Categories or the custom-field key.
Facet title set in the admin.
Up to 5 most frequent values among the top 100 matches.
object
Value to send back in filterBy. For categories
Text to show. For categories
Number of matching products (not capped by the number returned).
The search value as sent, for a “View all results” link.
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.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "Search As You Type functionality is disabled!"}{ "message": "The 'search' field is required."}{ "message": "The 'context' field is required."}{ "message": "The 'search' field must be a string."}{ "message": "The 'filterBy[0].type' field is required."}{ "message": "The object '' contains forbidden keys: 'limit'."}{ "message": "The 'context' field is required. The 'search' field is required."}{ "message": "formPayload is missing from request body"}{ "message": "The access token you provided is invalid."}{ "message": "Domain with the provided access token cannot be found."}{ "message": "Authorization header is malformed. It should look like `Bearer <string>`."}The domain is disabled, or value delivery is paused because usage exceeded the plan limit.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "Domain is disabled. Please reach out to support@releva.ai to enable it."}{ "message": "Value delivery is paused for this domain because usage exceeded the plan limit. Please raise your limit or reach out to support@releva.ai to resume."}Request body larger than 800 KB.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "request entity too large"}Unexpected server error. Also returned when Search As You Type has never been set up for the domain.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "An internal error occurred."}