Recommendations and Pathways API v2

Recommendations and Pathways APIs provide data for the Recommendations and Pathways widgets on mobile and desktop pages. These APIs are sent over HTTP 1.1 protocol and the response is JSON-formatted. Before you begin, you may want to visit the API Deployment page to learn about how our APIs work, the Authentication mechanism, and the best way to use our APIs.


Production:{widget type}/{widget_id}
Staging:{widget type}/{widget_id}

The widget types are listed in the next section below. The widget_id can be found in the Widget Configurator in the Dashboard.

Widget Types

There are 6 types of Recommendations and Pathways widgets:

  1. Category-based Widget
  2. Global Recommendation Widget
  3. Item-based Recommendation Widget
  4. Keyword-based Widget
  5. Personalization-based Widget
  6. Visual Search Widget

Each widget type uses a different API endpoint, and each widget API fetches results differently and solves for a specific use case. The table below lists suggested use cases for each widget type, and you can read more about each widget type in the Recommendations User Guide.

Widget typeAPI endpointAlgorithms supportedUse Case
  • Pathways widgets on category or landing pages
  • Business-driven custom recommendations widgets like new arrivals, product collections, etc. This could be on a category or landing page.
  • Trending Products Recommendations

  • Bestseller
  • Recommendations surfaced by Bloomreach based on the most popular or trending products in a particular segment.
  • Frequently bought together

  • Frequently viewed together

  • Similar products

  • Experience-driven recommendations
  • Recommendations surfaced by Bloomreach algorithms based on user actions on your site- individually or overall.
  • Pathways widgets on search or landing pages
  • Business-driven custom recommendations widgets like new arrivals, product collections, etc. This could be on a search or landing page.
  • Past Purchases

  • Recently Viewed Products
  • Personalized widget based on customer's purchase history.
  • Visual Search
  • Displays visually similar shoppable recommendations once the customer uploads an image.

    Example request

    curl -X GET \ ',6007840010&facet=true&domain_key=example&start=0&<Bloomreach Provided Account ID>&fields=pid&request_id=1331600000' \  
    -H 'auth-key: abc1d234e5fgh6ij'


    • API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.
    • Please note that the correct domain_key is mandatory in the API request. Starting March 2023, sending API requests without domain_key will return a 4xx error response. This applies to all Recommendations and Pathways APIs except Email Recommendations APIs.

    Changes from v1 API

    Some parameters in the v1 API are different in the v2 API:

    v1 parameterv2 parameterDescription
    qquery (Search)
    cat_id (Category)
    For Search Pathways, a query is entered in the search box or statically allocated for a landing page.

    For Category Pathways, the cat_id indicates the category being operated on.
    flfieldsThe field must include attributes that you want returned in your API response, such as product IDs and prices. The attributes are defined as in the product feed.


    Authentication in the v2 API

    The v1 API allows passing the auth-key as a query param, but the v2 API requires passing the auth-key as a request header. For example, -H 'auth-key: abc1d234e5fgh6ij'


    Filtering support

    The v2 APIs support advanced filtering, which you can read about on the Advanced Filtering Support for Recommendations and Pathways page