# Endpoints the Releva SDKs call

> The storefront and app endpoints the Releva JavaScript and mobile SDKs call, and the product blocks, banners and stories they receive in the page push, with the click, impression and event calls that report back. For teams that build their own client.

**The SDK makes these calls. You only need this page if you build your own client**: a storefront without the Releva JavaScript SDK, a block you render yourself, or an app that does not use a Releva mobile SDK. With an SDK installed, you call nothing on this page directly.

* Web: [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/)
* Apps: [Mobile SDKs overview](https://releva.ai/documentation/integrations/mobile/mobile-sdks-overview/), [iOS (Swift) SDK reference](https://releva.ai/documentation/integrations/ios-swift/sdk-reference/), [React Native SDK reference](https://releva.ai/documentation/integrations/react-native/sdk-reference/), [Connect your Flutter app](https://releva.ai/documentation/integrations/flutter/connect-your-flutter-app/), [Connect your Android app](https://releva.ai/documentation/integrations/android-kotlin/connect-your-android-app/)

Product blocks, banners and stories have no endpoint of their own. They reach the page or screen inside the **page push** response, and the client reports back through the **impressions** and **events** endpoints.

## Which SDK calls which endpoint

All calls go to `https://releva.ai/api/v0` (or `https://<realm>.releva.ai/api/v0`). The JavaScript SDK puts the access token in the path. The iOS, Flutter and React Native SDKs call the same routes without the path segment and send the token in a header instead.

| Endpoint                                               | JavaScript SDK                                                         | Mobile SDKs                                                         | What it does                                                                                                                |
| ------------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `POST /push/{accessToken}`, `POST /push`               | Every `Releva.push()`; `Releva.recommenderClicked()`                   | Every `track*` call; cart and wishlist changes after the first call | Sends the page or screen context. Returns `recommenders`, `banners`, `stories` and, when on, `nps`, `search` and `chatBot`. |
| `POST /impressions/{accessToken}`, `POST /impressions` | When a block or banner it drew becomes visible                         | When a banner is shown                                              | Records product block and banner impressions.                                                                               |
| `POST /push/events/{accessToken}`, `POST /push/events` | Banner clicks and closes, story and NPS widget events, page engagement | Banner clicks and closes, story events                              | Records one event per request.                                                                                              |
| `POST /pushSubscriptions/{accessToken}`                | After a push, with `serviceWorkerUrl` and granted permission           |                                                                     | Registers a web push subscription. See [Push notifications API](https://releva.ai/documentation/reference/push-notifications/overview/).     |
| `POST /appPush/tokens`                                 |                                                                        | `registerPushToken`                                                 | Registers an app push token. See [Push notifications API](https://releva.ai/documentation/reference/push-notifications/overview/).           |
| `POST /searchAsYouType/{accessToken}`                  | `Releva.searchAsYouType()` and the search dropdown                     |                                                                     | See [Search as you type API](https://releva.ai/documentation/reference/search-as-you-type/overview/).                                        |
| `POST /subscribe/request`, `POST /subscribe/check`     | `Releva.requestSubscribe()`, `Releva.checkSubscribed()`                |                                                                     | See [Consent API](https://releva.ai/documentation/reference/consent/overview/).                                                              |
| `POST /nps/{token}/submissions`                        | The NPS widget                                                         | `submitNpsResponse`                                                 | See [Surveys API](https://releva.ai/documentation/reference/surveys/overview/).                                                              |
| `/inbox/*` (six routes)                                |                                                                        | The App Inbox                                                       | See [Inbox API](https://releva.ai/documentation/reference/inbox/overview/).                                                                  |
| `GET` of the push’s `callbackUrl`                      |                                                                        | Push tap tracking                                                   | No authentication; the URL carries an encrypted payload.                                                                    |

The rest of this page covers the first three rows: the push response for product blocks, banners and stories, and the calls that report back.

## Authentication

Every call on this page takes your shop’s **access token**, the public key that ships in your page source. Never put the secret key in a browser or an app. Find the token under **Settings › Shop & Integration** ([Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)).

Send it in the path, `POST /push/{accessToken}`, as the JavaScript SDK does, or as a header on the path without it, as the mobile SDKs do:

```plaintext
authorization: Bearer $RELEVA_ACCESS_TOKEN
```

Authentication failures on the push answer **`400`**:

| Problem                            | Message                                                                                                              |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| No token in the path and no header | `Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required.` |
| Header is not `Bearer <token>`     | ``Authorization header is malformed. It should look like `Bearer <string>`.``                                        |
| Token is not a UUID                | `The access token you provided is invalid.`                                                                          |
| No shop has this token             | `Domain with the provided access token cannot be found.`                                                             |

A disabled shop answers **`402`** `Domain is disabled. Please reach out to support@releva.ai to enable it.`; a shop whose usage exceeded its plan answers **`402`** `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 format

* Send JSON with `content-type: application/json`. The JavaScript SDK sends a form body instead, with one field `formPayload` = `base64(encodeURIComponent(JSON.stringify(body)))`. Any other content type answers `400 {"message":"Request body is missing."}`; a form body without `formPayload` answers `400 {"message":"formPayload is missing from request body"}`.
* The `context` object of the push is validated strictly: an unknown key answers `400`, for example `{"message":"The object 'page' contains forbidden keys: 'color'."}`.
* Send a **browser user agent**. Requests whose user agent is a bot, including curl’s default `curl/x.y`, get empty `recommenders`, `banners` and `stories` with status `200`. This is the most common reason a test with curl shows nothing.

## The page push

`POST /push/{accessToken}`

The fields of `context` that decide what comes back:

| Field                                                          | Type             | Effect                                                                                                                                                                                                       |
| -------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page.token`                                                   | UUID             | The Releva page (**Token:** on the page’s list). Without it, Releva matches a page by the pathname of `page.url` against the page’s **URL Path**; without either, nothing is returned.                       |
| `page.url`                                                     | absolute URL     | Used for the page match above and for each block’s **URL filter**. Must be absolute (`https://...`): a relative URL answers `500`. The Swift SDK sends no page URL, so URL filters do not apply in iOS apps. |
| `page.locale`                                                  | ISO-639-1 (`en`) | Picks the title translation and the **Locales to Display** rule. Defaults to the shop locale. `en-US` answers `400 page.locale must be a valid ISO-639-1 code! Got en-US instead.`                           |
| `page.currency`                                                | ISO-4217         | Prices in the response are converted to it. Defaults to the shop currency.                                                                                                                                   |
| `page.ids`                                                     | string\[]        | Product ids already on the page. **Discover** blocks exclude them, **Re-Rank** blocks return only them, **Highlight** blocks ignore them. A Re-Rank block without ids returns no products.                   |
| `page.blocks.tags`                                             | string\[]        | Return only product blocks, banner blocks and stories that carry at least one of these tags. Product blocks without tags are dropped when this is sent.                                                      |
| `product.id`, `cart.products`, `page.categories`, `page.query` |                  | Context for the feed’s algorithm (similar products, bought together, search).                                                                                                                                |
| `deviceId`, `sessionId`, `profile`                             |                  | Who the visitor is: segment membership and the A/B control group.                                                                                                                                            |
| `mode`                                                         | `"debug"`        | Returns switched-off and out-of-schedule product blocks too and adds `query` and `filter` to each. The JavaScript SDK sends it when the page URL has `?rlv_mode=debug`.                                      |
| `rid`, `rpid`, `rpos`, `pfid`                                  |                  | Click attribution from the previous page; see [Record a product block click](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#record-a-product-block-click).                                                                                                 |

```plaintext
curl -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36' \
  -d '{
    "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 response is `200` with `recommenders` (product blocks), `banners` and `stories`, each described below. Every array can be empty: no page matched, nothing passed the rules, the visitor is in an A/B control group, or the caller is a bot.

The page configuration is cached for **60 seconds** per access token and page. Saving a block in the admin clears the cache, so an edit shows on the next push; a block that starts or ends by schedule can take up to a minute.

### Check the tracking snippet with curl

Use this to prove that an access token is valid and the shop is running before you debug the storefront snippet. This is the smallest valid request:

```plaintext
curl -sS -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  --data '{"context":{"cart":{"products":[]}}}'
```

Response `200`:

```plaintext
{
  "recommenders": [],
  "banners": [],
  "stories": [],
  "push": { "vapidPublicKey": "<vapid-public-key>" },
  "gtmId": null,
  "clientIp": "203.0.113.10",
  "userAgent": "curl/8.7.1"
}
```

A `200` means the token and the shop are fine. `recommenders`, `banners` and `stories` stay empty here: the request carries no page token and uses curl’s default user agent. Every successful call records an anonymous page view, so don’t run it in a loop. For the error messages, see [Authentication](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#authentication) and [Errors](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#errors).

## Product blocks in the /push response

`recommenders` holds one object per product block, in the block’s priority order on the page. One block, one product shown (`cssStyles` cut):

```plaintext
{
  "recommenders": [
    {
      "token": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b",
      "name": "Demo popular on product page",
      "title": "Popular right now",
      "mode": "highlight",
      "productFeedId": 37,
      "segmentId": 1,
      "tags": [],
      "meta": { "algorithm": "popular" },
      "displayType": "static",
      "cssSelector": "#releva-demo-block",
      "displayStrategy": "beforeend",
      "template": {
        "id": 34,
        "body": "<div class=\"rlv-demo-block\"><h3>{{title}}</h3><ul>{{#each response}}<li><a href=\"{{url}}\">{{name}}</a> <span>{{price}} {{currency}}</span></li>{{/each}}</ul></div>"
      },
      "randomize": false,
      "advancedStyling": false,
      "response": [
        {
          "id": "DEMO-1003",
          "name": "Leather Sandals",
          "description": "Hand-stitched leather sandals with a cushioned sole.",
          "url": "https://demo-store.example.com/products/leather-sandals?rlv_rid=8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b&rlv_rpid=DEMO-1003&rlv_rpos=1&rlv_pfid=37",
          "imageUrl": "https://demo-store.example.com/images/leather-sandals.jpg",
          "sku": "DEMO-1003-40",
          "available": true,
          "categories": ["Women/Shoes/Sandals"],
          "custom": { "string": [{ "key": "size", "values": ["38", "40"] }], "numeric": [], "date": [] },
          "locale": "en",
          "currency": "EUR",
          "listPrice": 59,
          "discountPrice": null,
          "price": 59,
          "discount": 0,
          "discountPercent": 0,
          "mergeContext": { "rid": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b", "rpid": "DEMO-1003", "rpos": 1, "pfid": 37 },
          "createdAt": "2026-10-20T20:05:48.278Z",
          "updatedAt": "2026-10-20T20:05:48.278Z"
        }
      ]
    }
  ]
}
```

| Field                                                  | Meaning                                                                                                                                                                                                                      |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                                                | The block’s id. It is the `rid` of a click and the `token` of an impression.                                                                                                                                                 |
| `name`, `title`                                        | Admin name; the title for `page.locale` (its translation when one exists), or `null`.                                                                                                                                        |
| `mode`                                                 | `highlight`, `discover` or `reRank`.                                                                                                                                                                                         |
| `productFeedId`, `segmentId`, `meta.algorithm`, `tags` | The feed and segment that filled the block, the feed’s algorithm, the block’s tags.                                                                                                                                          |
| `displayType`                                          | `static` (inline), `popup`, `flyout`, `bar` or `custom`. Non-static blocks also carry a `banner` object with the overlay settings.                                                                                           |
| `cssSelector`, `displayStrategy`                       | Where to insert: the first match of `document.querySelector(cssSelector)`, at `beforebegin`, `afterbegin`, `beforeend`, `afterend` or `replace` (hide the target and insert after it). `cssSelector` is `null` when not set. |
| `template`                                             | The layout as a Handlebars template in `body`. Absent when the block has no layout.                                                                                                                                          |
| `response`                                             | The products. Empty for a visitor in the A/B control group, when the feed found fewer products than the block’s minimum, or when the query failed.                                                                           |
| `randomize`, `advancedStyling`, `cssStyles`            | Shuffle (already applied), and the overlay styling with defaults filled in.                                                                                                                                                  |
| `query`, `filter`                                      | Only with `mode: "debug"`: the search query and the feed rules.                                                                                                                                                              |

Each product in `response` has the catalog fields (`id`, `name`, `description`, `url`, `imageUrl`, `sku`, `available`, `categories`, `custom`, `data`, `locale`, `createdAt`, `updatedAt`, `publishedAt`), the prices converted to `page.currency` (`currency`, `listPrice`, `discountPrice`, `price`, `discount`, `discountPercent`), the click parameters appended to `url`, and the same values in `mergeContext` for links you build yourself.

**Which blocks come back.** In this order: the page is found by `page.token`, else by pathname; the block is on and inside its start and end time (skipped in `debug` mode); it has a feed and a segment; it matches `page.blocks.tags` if sent; the visitor matches the audience (segment, inverted by **Exclude**, combined with the profile filter); the URL passes the block’s URL filter (text fragments separated by `|`, substring match; no `page.url` means the rule passes); the user agent is not a bot; `page.locale` is in the block’s locales or the list is empty. More on these rules in [How product blocks work](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/).

**Draw a block yourself.** When a block has no `template` or no `cssSelector`, the JavaScript SDK does not draw it and passes it to the `Releva.push` callback instead. Render `response` with your own markup and keep each product’s `url` as returned so that clicks are recorded. Then [report impressions](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#report-impressions) yourself: the SDK only tracks the blocks it drew.

### Record a product block click

A click is recorded on the **next** push, from the parameters Releva appended to the product URL: `rlv_rid` (block token), `rlv_rpid` (product id), `rlv_rpos` (position) and `rlv_pfid` (feed id). The JavaScript SDK copies them from the landing URL into `context.rid`, `rpid`, `rpos` and `pfid`. Releva writes a `recommenderClick` event and attributes the visitor’s cart additions and purchases of the next day to the block.

```plaintext
curl -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -H 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36' \
  -d '{
    "context": {
      "deviceId": "demo-device-pb-1",
      "sessionId": "demo-session-pb-1",
      "rid": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b",
      "rpid": "DEMO-1003",
      "rpos": 1,
      "pfid": 37,
      "page": {
        "token": "3f1c2a9e-5b7d-4c1e-9a2b-7d6e5f4a3b21",
        "url": "https://demo-store.example.com/products/leather-sandals?rlv_rid=8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b&rlv_rpid=DEMO-1003&rlv_rpos=1&rlv_pfid=37"
      },
      "product": { "id": "DEMO-1003" }
    }
  }'
```

Response: `200` with the usual push body for the landing page. `rid` must be a UUID and `rpos` a number of 1 or more. For a click that does not load a new page (a quick-view dialog in a single-page app), the JavaScript SDK has `Releva.recommenderClicked(rpid, rid)`: it sends a push with only those two fields.

## Banners in the /push response

`banners` holds one object per banner **block** that passed the serving rules ([When a block is served](https://releva.ai/documentation/learn/banner-blocks/how-banners-work/#when-a-block-is-served)), in priority order and cut to the page’s **Max Banners Displayed**. The client decides *when* to show each block from `trigger`.

```plaintext
{
  "banners": [
    {
      "token": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b",
      "bannerId": 1,
      "design": null,
      "segmentId": 3,
      "displayType": "bar",
      "delaySeconds": null,
      "scrollPercentage": 30,
      "cssSelector": "",
      "trigger": "scrollPercentage",
      "leaveIntentBackButton": false,
      "name": "Demo summer sale bar",
      "displayStrategy": "afterbegin",
      "html": "<div>…<a href=\"https://demo-store.example.com/collections/summer-sale?rlv_bid=7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b\">Shop the sale</a></div>",
      "tags": [],
      "mergeContext": {},
      "displayPosition": null,
      "advancedStyling": false,
      "cssStyles": {
        "overlayColor": "rgba(0,0,0,0.4)",
        "cardBackgroundColor": "#fefefe",
        "closeButtonSymbol": "X",
        "closeButtonColor": "#000",
        "closeButtonBackgroundColor": "#fff",
        "customCss": ""
      }
    }
  ]
}
```

| Field                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                                                     | The banner block’s UUID. Send it back as `token` in an impression and as `attributions.bannerBlockId` in a banner event.                                                                                                                                                                                                                                  |
| `bannerId`                                                  | The banner’s numeric id. Send it back as a string.                                                                                                                                                                                                                                                                                                        |
| `name`                                                      | The block’s admin name, for debugging.                                                                                                                                                                                                                                                                                                                    |
| `segmentId`                                                 | The id of the banner’s segment. Send it back as a string in an impression.                                                                                                                                                                                                                                                                                |
| `design`                                                    | The design document in the Unlayer format the app SDKs draw from (a banner built in the Releva builder also carries the builder’s own document), or `null` for an HTML banner. On the web, render `html`.                                                                                                                                                 |
| `displayType`                                               | `static`, `popup`, `flyout`, `bar` or `custom`: the **Display mode**.                                                                                                                                                                                                                                                                                     |
| `trigger`                                                   | One of `immediately`, `scrollPercentage`, `delaySeconds`, `leaveIntent`, `wishlistChanged`, `cartChanged`. Always `immediately` for `static`.                                                                                                                                                                                                             |
| `delaySeconds`, `scrollPercentage`, `leaveIntentBackButton` | Parameters for the matching trigger; `null` or `false` otherwise.                                                                                                                                                                                                                                                                                         |
| `cssSelector`, `displayStrategy`                            | For `static` blocks: where to insert the HTML, and how (`beforebegin`, `afterbegin`, `beforeend`, `afterend` or `replace`, the **Insert strategy**).                                                                                                                                                                                                      |
| `html`                                                      | The banner’s HTML, already personalised with the visitor’s merge tags. Every trackable link carries `rlv_bid=<token>`, and `rlv_u` when the link leaves the shop’s host.                                                                                                                                                                                  |
| `tags`                                                      | Tag names, for clients that filter by tag.                                                                                                                                                                                                                                                                                                                |
| `mergeContext`                                              | Tracking context the SDK attaches to links.                                                                                                                                                                                                                                                                                                               |
| `displayPosition`, `advancedStyling`, `cssStyles`           | The **Appearance** settings: placement (`top`, `bottom`, `left`, `right` or `null` for automatic), whether the author styled the block, and the overlay, card and close-button styles. `cssStyles` is always complete: Releva merges the block’s own values over the standard defaults. Numeric values are strings without a unit (the SDK appends `px`). |

To report what the visitor did with a banner, send an [impression](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#report-impressions) when it is shown and a [banner event](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#banner-and-story-events) when it is clicked or closed.

## Stories in the /push response

`stories` holds the stories for the page or screen, on the web and in apps. It is empty when none of the display rules pass ([When a story is shown](https://releva.ai/documentation/learn/stories/how-stories-work/#when-a-story-is-shown)). The client decides *when* to open the story from `trigger`.

```plaintext
{
  "stories": [
    {
      "token": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b",
      "storyId": 1,
      "name": "Demo summer lookbook",
      "trigger": "delaySeconds",
      "leaveIntentBackButton": false,
      "delaySeconds": 3,
      "scrollPercentage": null,
      "autoPlayDurationSeconds": 6,
      "endBehavior": "dismiss",
      "progressIndicatorColor": "#333333",
      "progressIndicatorInactiveColor": "#33333340",
      "tags": [],
      "slides": [
        {
          "id": 11,
          "position": 0,
          "html": "<div>…<a href=\"https://demo-store.example.com/collections/summer?rlv_stid=7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b\">Shop now</a></div>",
          "design": null,
          "durationSeconds": 6,
          "actionType": "none",
          "actionUrl": null,
          "actionLabel": null
        }
      ],
      "mergeContext": {}
    }
  ]
}
```

| Field                                                       | Meaning                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                                                     | The story’s UUID. Send it back as `attributions.storyId` on every story event.                                                                                                                                                                            |
| `storyId`, `name`                                           | The admin id and name, for debugging.                                                                                                                                                                                                                     |
| `trigger`                                                   | One of `immediately`, `scrollPercentage`, `delaySeconds`, `leaveIntent`, `wishlistChanged`, `cartChanged`.                                                                                                                                                |
| `delaySeconds`, `scrollPercentage`, `leaveIntentBackButton` | Parameters for the matching trigger; `null` or `false` otherwise.                                                                                                                                                                                         |
| `autoPlayDurationSeconds`                                   | Default time per slide, 1 to 60.                                                                                                                                                                                                                          |
| `endBehavior`                                               | `dismiss`, `loop` or `stayOnLast`.                                                                                                                                                                                                                        |
| `progressIndicatorColor`, `progressIndicatorInactiveColor`  | Hex colours for the progress bars; may be `null`.                                                                                                                                                                                                         |
| `tags`                                                      | Tag names, for clients that filter by tag.                                                                                                                                                                                                                |
| `slides[]`                                                  | Sorted by `position`. `html` is already personalised with the visitor’s merge tags, and every trackable link carries `rlv_stid=<token>` (and `rlv_u` when the link leaves the shop’s host). `durationSeconds` is the slide override or the story default. |
| `slides[].actionType`, `actionUrl`, `actionLabel`           | `none`, `deepLink`, `webUrl` or `dismiss`, with the target and label. Meant for mobile clients; the admin form has no field for them, so they are `none` / `null` unless set through other tooling.                                                       |
| `mergeContext`                                              | Tracking context the SDK attaches to story links.                                                                                                                                                                                                         |

## Report impressions

`POST /impressions/{accessToken}`

Records one `recommenderImpression` event per product block and one `bannerImpression` event per banner. The JavaScript SDK calls it when a block or banner it drew becomes visible (at least 25% of a product block), once per block per page load; the mobile SDKs call it when a banner is shown. Call it yourself only for what you rendered.

| Field                                      | Required                          | Notes                                                                            |
| ------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------- |
| `recommenders`                             | one of `recommenders` / `banners` | Items `{ token, productFeedId, segmentId }` copied from the block; no other keys |
| `banners`                                  | one of `recommenders` / `banners` | Items `{ token, bannerId, segmentId }` copied from the banner; no other keys     |
| `profileId` or `deviceId`                  | one of the two                    | The visitor; the SDK sends the profile id when known, else the device id         |
| `sessionId`, `url`, `email`, `phoneNumber` | no                                |                                                                                  |

`productFeedId`, `bannerId` and `segmentId` must be **strings** here, although the push returns them as numbers.

```plaintext
curl -X POST "https://releva.ai/api/v0/impressions/$RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "recommenders": [
      { "token": "8b0e6f3a-2c4d-4e5f-9a1b-3c2d1e0f9a8b", "productFeedId": "37", "segmentId": "1" }
    ],
    "banners": [
      { "token": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b", "bannerId": "1", "segmentId": "3" }
    ],
    "deviceId": "demo-device-pb-1",
    "sessionId": "demo-session-pb-1",
    "url": "https://demo-store.example.com/products/linen-summer-shirt"
  }'
```

Response: `200` `{}`. Impressions are not deduplicated by the server.

| Cause                                | Status | Body                                                                              |
| ------------------------------------ | ------ | --------------------------------------------------------------------------------- |
| Neither `profileId` nor `deviceId`   | 400    | `{"error":"One of profileId or deviceId is required"}`                            |
| Neither `recommenders` nor `banners` | 400    | `{"error":"At least one of banners or recommenders must be provided"}`            |
| `productFeedId` sent as a number     | 400    | `{"message":"The 'recommenders[0].productFeedId' field must be a string."}`       |
| Extra key in an item                 | 400    | `{"message":"The object 'recommenders[0]' contains forbidden keys: 'position'."}` |

The handler’s own checks answer with an `error` key; validation and authentication answer with `message`.

## Banner and story events

`POST /push/events/{accessToken}`

Send one request per event with `content-type: application/json`.

```plaintext
curl -X POST "https://releva.ai/api/v0/push/events/$RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "deviceId": "demo-device-pb-1",
    "sessionId": "demo-session-pb-1",
    "action": "bannerClick",
    "attributions": {
      "bannerBlockId": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b",
      "bannerId": "1"
    },
    "page": { "url": "https://demo-store.example.com/" }
  }'
```

| Field                                                 | Required          | Meaning                                                                                                                               |
| ----------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `deviceId`                                            | yes               | The visitor’s device id, the same value you send as `context.deviceId` on the push. Also the key for the **Show until click** memory. |
| `sessionId`                                           | yes               | The visitor’s session id.                                                                                                             |
| `action`                                              | yes               | One of the actions below.                                                                                                             |
| `attributions.bannerBlockId`, `attributions.bannerId` | for banner events | The block `token` and the `bannerId` (as a string) from the push response. Send both.                                                 |
| `attributions.storyId`                                | for story events  | The story `token` from the push response.                                                                                             |
| `profileId`                                           | no                | The known profile id, when the visitor is identified. One of `profileId` or `deviceId` must be non-empty.                             |
| `page.url`, `page.token`                              | no                | The page the event happened on.                                                                                                       |

| `action`          | Send it when                                    | Counted as                                                          |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
| `bannerClick`     | The visitor follows a link in the banner        | Clicks; also attributes later cart adds and orders to the block     |
| `bannerClose`     | The visitor closes the banner                   | Closes                                                              |
| `storyImpression` | The story opens                                 | Impressions                                                         |
| `storySlideView`  | A slide becomes visible                         | Slide Views                                                         |
| `storySlideClick` | The visitor follows a link or action in a slide | CTA Clicks; also attributes later cart adds and orders to the story |
| `storyComplete`   | The last slide finishes                         | Completions                                                         |
| `storyClose`      | The visitor closes the story                    | Closes                                                              |

Banner impressions do not go here: send them to [`/impressions`](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#report-impressions). A click and a close also set the **Show until click** memory for the device; see [How banners work](https://releva.ai/documentation/learn/banner-blocks/how-banners-work/) and [How stories work](https://releva.ai/documentation/learn/stories/how-stories-work/). A banner click is also detected when the visitor lands on an `rlv_bid` link; the two reports are deduplicated by block and device, so sending `bannerClick` does not double count.

Response: `202` `{}`. The event is stored asynchronously and appears in **Data Platform › Events** and on the block’s or story’s statistics shortly after. An unknown `bannerBlockId` or `storyId` is also accepted with `202`, stored as an ordinary event and not counted anywhere, so check the ids you send back.

| Message (`400`)                                                        | Cause                                                              |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `The access token you provided is invalid.`                            | The token is not a shop’s access token.                            |
| `The 'deviceId' field is required. The 'sessionId' field is required.` | Required fields missing; several problems are joined with a space. |
| `One of profileId or deviceId is required.`                            | `deviceId` was sent empty and there is no `profileId`.             |
| `The 'action' field must be a string.`                                 | Wrong type.                                                        |

## Errors

| Status | When                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200`  | Push and impressions succeeded. Empty arrays in a push response are also a success.                                                                          |
| `202`  | An event was accepted.                                                                                                                                       |
| `400`  | Authentication failed, validation failed, or the body could not be parsed. One message, as above.                                                            |
| `402`  | The shop is disabled or its delivery is paused.                                                                                                              |
| `500`  | `{"message":"An internal error occurred."}`. Seen for a `page.token` that is not a UUID and for a relative `page.url`; fix the request rather than retrying. |

## Limits

* Body size: 800 KB JSON, 2 MB form-encoded.
* Rate limits: none.
* Per page, at most 10 running product blocks by default. This is enforced when a block is saved or switched on in the admin, not on the push.
* Configuration cache: 60 seconds, cleared when a block is saved.

## Versioning

All endpoints are under `/api/v0`. `context` is validated strictly, so send new context keys only after they appear in the reference. Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/).

## Next steps

* [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/): Use the SDK instead of calling these endpoints yourself.
* [Mobile SDKs overview](https://releva.ai/documentation/integrations/mobile/mobile-sdks-overview/): Pick the SDK for your app and see what it sends.
* [How product blocks work](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/): Learn the rules that decide which product blocks a visitor gets.
* [Events API overview](https://releva.ai/documentation/reference/events/overview/): Send custom and search events from your own client or backend.