Parameters for the thematic API with HTML responses - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Parameters for the thematic API with HTML responses

Quick reference for all parameters

This table provides a list of each parameter and a description. A yes flag in the Required column indicates that the parameter is required for all thematic API calls, not some.


You can escape non-alphanumeric characters in your parameter values, using  URL percent-encoding conventions.

Using * query
When you use the query '*' as 'q=*' in the API request, the latency of the response will vary depending on your catalog size and it may not adhere to the Bloomreach's standard SLA. Further, please note that except for include/exclude operation, other merchandising options operations such as boost/bury or slots do not work on * query parameters.

Parameter name






yes string The Bloomreach-provided authentication key for your account ID.



yes integer The Bloomreach-provided ID for your account.  


yes string Specifies the type of the device that your customer is using to send the request. desktop


no string

Specifies the internal environment where Bloomreach returns a response. This value is always prod for thematic pages.

page_name yes string The dynamically-generated name of the thematic page. white-dresses


yes string Specifies the template version. The default value is v1 . v1
url yes string The URL for the webpage that is sending the request.
user_agent yes string

The browser user agent, which lets Bloomreach track web crawling.


More details

acct_auth and acct_id parameters

The values for the acct_auth and acct_id parameters are the same for all of your licensed Bloomreach products. The parameter names are different, but the values are the same. Make sure that you're using the correct parameter names for your licensed Bloomreach products.

device_type parameter

The device_type parameter specifies your customer’s device type. If you have different page templates for different devices, then Bloomreach returns a page formatted according to the appropriate page template. Here are some common values:

  • desktop  (default)
  • mobile
  • tablet

Extrapolate this parameter value from the HTTP headers supplied by your customer’s browsing request.

page_name parameter

The page_name parameter value is the dynamically-generated name of the thematic page that your customer is loading. Bloomreach extracts the name from the request page. Hyphens replace spaces in this value and there are no extra white spaces around the value.

You can append your thematic URL to your page_name parameter. Here's the recommended method:

Create a rule to rewrite any URL that has the pattern, your-thematic-url, to a single template on the server that receives page_name parameters. This template sends the request to the Bloomreach Thematic server, which returns the response.

response_version parameter

The response_version parameter specifies the template version. If you create a new design for your category page, then you can move your thematic pages to that new design. The default value is v1. New designs require you to increment or otherwise update this value.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?