Introduction

Welcome to the Bloomreach Discovery API Documentation!

What are the Discovery APIs?


The Discovery APIs provide your developers a convenient way to interact with the Bloomreach Discovery modules through simple HTTP methods over our REST API. This provides a smooth and familiar solution to integrate and use the Discovery data in your applications.
For almost all the APIs, the response is in JSON format. You can tweak around with a wide range of parameters for each endpoint to make a tailor-made request to get exactly what you need.

Bloomreach provides different APIs for different modules and functionalities. These include:

  • Catalog Management APIs - The Catalog Management APIs are used to send your product catalog data to Bloomreach
  • Search and Merchandising APIs - These APIs provide data for showing Autosuggestions and Content Search results, and other effects caused by your Merchandising rules
  • Recommendations and Pathways APIs - These APIs provide data for showing products in different Recommendation widgets like Frequently Bought Together, New Arrivals etc., that enhance the product discovery experience
  • SEO APIs - These APIs provide product data to create Thematic pages and widgets like Related Categories to optimize your link structure
  • Other Resources like the Pixel API and Bloomreach Discovery SDK

What are the APIs used for?


The Discovery APIs are a requisite in the entire lifecycle of using Bloomreach Discovery, right from integration of the modules to finally presenting the data and configurations on your webpage or application to the customers.

You begin by using the Catalog Management APIs to send your product or content catalog data to Bloomreach. Once you have sent and indexed your catalog data, you can continue to use Discovery features and create new rules and configurations through the Dashboard.
Now, to fetch and show the effects of those changes in the front-end of your website or mobile application, you’ll use the feature-specific Discovery APIs.

For example, you created a “Frequently bought together” widget through the Bloomreach Dashboard. But, to actually display the widget on your frontend, you must fetch the widget data through our Recommendations API (in this case, a list of products in that widget).

Endpoints


All Discovery APIs have a Staging endpoint to perform tests and a Production endpoint to serve your live traffic.
The exact URLs of these endpoints differ for each API and can be found on their own pages.

📘

A detailed technical specification of the allowances and limitations of both the endpoints can be found on the Environment Details page.

Authentication


This is a high-level overview of the Authentication mechanisms that you should be aware of so you’re prepared to use the Discovery APIs.

👍

You are provided with an API key and an Authentication key for your account by your Bloomreach representative at the time of the integration process.

For the Catalog Management API, you need to send your account's API key in the Authorization header as the Bearer value. Sending this key is mandatory for each request to the Catalog Management endpoints.

For the Search and Merchandising APIs, if your account is configured to use authentication (at the time of integration), you need to send your account’s Authentication key (different from the API key) inside the auth key parameter along with the other query parameters.

❗️

Only send your private auth_key for server side requests. Pass it as an empty value for client-side calls.

Requests to the SEO APIs are almost always server-side, hence, sending the Authentication key is mandatory inside the auth_key parameter along with the other query parameters.

The Recommendations and Pathways APIs do not need any of these keys since these are almost always client-side calls. So you can simply make these calls by using your Bloomreach account ID.

Here’s a quick summary of all the Authentication mechanisms:

API

API key in header

Authentication key in auth_key parameter

Mandatory

Catalog Data Management API

✅ yes

❌ no

✅ yes

Search and Merchandising APIs

❌ no

✅ yes (If your account is configured for it)

❌ no

Recommendations and Pathways APIs

❌ no

❌ no

❌ no

SEO APIs

❌ no

✅ yes

✅ yes