Get the product blocks for a page (access token in the header)
- Path
/push- Auth
- Access token · browser or app
const url = 'https://releva.ai/api/v0/push';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"context":{"deviceId":"demo-device-pb-1","sessionId":"demo-session-pb-1","page":{"token":"3f1c2a9e-5b7d-4c1e-9a2b-7d6e5f4a3b21","url":"https://demo-store.example.com/products/linen-summer-shirt","locale":"en","currency":"EUR"},"product":{"id":"DEMO-1001"},"cart":{"products":[]}}}'};
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/push \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "context": { "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "page": { "token": "3f1c2a9e-5b7d-4c1e-9a2b-7d6e5f4a3b21", "url": "https://demo-store.example.com/products/linen-summer-shirt", "locale": "en", "currency": "EUR" }, "product": { "id": "DEMO-1001" }, "cart": { "products": [] } } }'The page push, with the access token sent as authorization: Bearer <accessToken> instead of in the path.
The JavaScript SDK uses POST /push/{accessToken} (no header, so no CORS pre-flight); server-side renderers and
tests can use this form. The response carries the product blocks of the Releva page identified by
context.page.token (or, without a token, by the pathname of context.page.url).
A block is returned only if it is switched on and inside its start/end time, has a product feed and a segment,
matches context.page.blocks.tags (if sent), the visitor’s segment, the URL rule and the locale rule, and the
caller is not a bot. Requests with a bot user agent, including curl’s default one, get "recommenders": [].
A block that returns fewer products than its minimum, or a visitor in the A/B control group, gets the block with
"response": []. context.mode: "debug" returns switched-off blocks too and adds query and filter.
Configuration changes apply on the next push; otherwise the page configuration is cached for 60 seconds.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Only the context fields that affect product blocks are listed. The context object is strict: an undeclared key answers 400. See the events-tracking fragment for the full context (cart, profile, events, wishlist…).
object
Sent by the SDK (client name, version); not used for product blocks.
object
object
debug (from ?rlv_mode=debug) returns switched-off and out-of-schedule blocks and adds query/filter.
layout-edit and placement-edit are used by admin editing sessions. Other values change nothing.
object
Token of the Releva page (one per page type). Without it, a page whose pathname equals the pathname of url is used.
Absolute URL of the current page. Checked against each block’s URL rule.
ISO-639-1. Picks the title translation and the locale rule. Defaults to the domain locale.
ISO-4217. Prices are converted to it. Defaults to the domain currency.
Ids of the products already on the page. Discover blocks exclude them; Re-Rank blocks return only them.
object
object
object
Return only blocks that have at least one of these tags.
The product on a product page.
object
object
object
Token of the block whose product was clicked (from rlv_rid).
Id of the clicked product (from rlv_rpid).
Position value from rlv_rpos.
Feed that filled the block (from rlv_pfid).
Example
{ "context": { "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "page": { "token": "3f1c2a9e-5b7d-4c1e-9a2b-7d6e5f4a3b21", "url": "https://demo-store.example.com/products/linen-summer-shirt", "locale": "en", "currency": "EUR" }, "product": { "id": "DEMO-1001" }, "cart": { "products": [] } }}object
Base64(encodeURIComponent(JSON.stringify(body))). What the SDK sends.
Example generated
formPayload=exampleResponses
Section titled “Responses”Personalized elements for the page.
object
One product block, as returned by the page push and passed to the layout as Handlebars data.
object
Block token. Used as rid for clicks and token for impressions.
Internal name.
Display title
object
Element the block is inserted next to (first match).
The layout. Empty when the block has no layout; the SDK then passes the block to your callback.
object
Handlebars template.
Empty for the A/B control group, when fewer than the block’s minimum were found, or on a query error.
object
Product URL with rlv_rid
object
object
The page currency.
Converted to the page currency.
The click-tracking values, for links you build yourself.
object
Overlay styling with defaults filled in.
object
Overlay settings for non-static display types.
object
Only with mode debug.
object
Only with mode debug.
object
object
object
object
Example
{ "recommenders": [ { "mode": "highlight", "meta": { "algorithm": "popular" }, "displayStrategy": "beforebegin", "displayType": "static" } ]}Authentication or validation error.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "Request body is missing."}{ "message": "Authorization header is malformed. It should look like `Bearer <string>`."}{ "message": "Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required."}{ "message": "The access token you provided is invalid."}{ "message": "Domain with the provided access token cannot be found."}{ "message": "page.locale must be a valid ISO-639-1 code! Got en-US instead."}{ "message": "The object 'page' contains forbidden keys: 'color'."}{ "message": "formPayload is missing from request body"}The domain is disabled, or value delivery is paused because usage exceeded the plan.
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."}Unexpected error. Observed for a page.token that is not a UUID and for a relative page.url.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "An internal error occurred."}