Welcome to the Bloomreach Discovery API Documentation!
Bloomreach Discovery APIs
The Discovery APIs provide your developers with a convenient way to interact with the Bloomreach Discovery modules through simple HTTP methods over our REST APIs. This is a smooth and familiar solution to integrate and use the Discovery data in your applications.
The response from almost all APIs is in JSON format. You can tweak a wide range of parameters for each API to make a tailor-made request and get exactly what you need to work with Discovery.
Bloomreach provides different APIs to use different modules and functionalities. These include:
- Catalog Management APIs - The Catalog Management APIs are used to send your product catalog data to Bloomreach and configure your Catalogs.
- Search and Merchandising APIs - These APIs allow you to use Discovery Search and Merchandising features. They also include:
- Autosuggest API - Provides data for showing Autosuggestions with search
- Content Search API - Provides Content Search results
- 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. They also include:
- Pixel API - Used to integrate Bloomreach Pixels on non-JS or other environments.
- SEO APIs - These APIs provide product data to create Thematic pages and widgets like Related Categories to optimize your link structure
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).
OpenAPI specs
The detailed OpenAPI specifications for all the Discovery APIs can be found on GitHub:
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 used in the Discovery APIs.
Keys
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.
To create new API Keys, or manage your existing keys, refer to this guide.
For the Catalog Management APIs, 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 API 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 APIs | ✅ 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 |