openapi: 3.1.0
info:
title: Workspace Imports Autosuggest API v2 Personalization-based widgets API
description: 'API to programmatically trigger an existing workspace-scoped
import in Bloomreach Engagement.
'
version: '2.1'
servers:
- url: https://api.bloomreach.com
description: Bloomreach API
security:
- basicAuth: []
tags:
- name: Personalization-based widgets
paths:
/personalized/{widget_id}:
get:
tags:
- Personalization-based widgets
summary: Personalized widget
operationId: personalization-based-widget-api
parameters:
- $ref: '#/components/parameters/WidgetId'
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BrUid'
- $ref: '#/components/parameters/DomainKey'
- name: query
in: query
description: 'Your site visitor''s search query. Search queries are composed of one or more terms.
You can percent encode spaces between terms as `%20`, or you can leave the spaces unencoded.
The example value shown here, <i>cable</i>, is included for your convenience to send a request with <b>Try It</b>.
'
required: true
example: cable
schema:
type: string
default: cable
- name: user_id
in: query
description: 'The universal customer ID of the user. Required for Personalization-based widgets.
The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking.
This way, Bloomreach recognizes users in a way that''s aligned with your system.
Use an anonymous string. Don''t use email or other personally identifiable information.
The example value shown here, <i>abc123</i>, is included for your convenience to send a request with <b>Try It</b>.
'
required: true
example: abc123
schema:
type: string
default: abc123
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/Url'
- $ref: '#/components/parameters/RefUrl'
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/ContentInjection'
- $ref: '#/components/parameters/Rows'
- $ref: '#/components/parameters/ViewId'
deprecated: false
/personalized/{recently_viewed_widget_id}:
get:
tags:
- Personalization-based widgets
summary: Recently viewed widget
operationId: recently-viewed-widget-api
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BrUid'
- $ref: '#/components/parameters/DomainKey'
- name: recently_viewed_widget_id
in: path
description: 'The ID of the Recently Viewed widget, which can be found in the [Widget Configurator](https://documentation.bloomreach.com/discovery/docs/widget-configurator) in the Dashboard.
The example value shown here, <i>1jwy7eg9</i>, is included for your convenience to send a request with <b>Try It</b>.
'
schema:
type: string
default: 1jwy7eg9
required: true
example: 1jwy7eg9
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/Url'
- $ref: '#/components/parameters/RefUrl'
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/ContentInjection'
- $ref: '#/components/parameters/Rows'
- $ref: '#/components/parameters/ViewId'
- name: auth_key
in: query
description: 'The Bloomreach-provided authentication key for the Bloomreach account that''s sending the request.
Widget API calls are client-side, so you can leave `auth_key` empty.
'
schema:
type: string
- name: user_id
in: query
description: 'The universal customer ID of the user. Required for Personalization-based Recommendation widgets.
The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking.
This way, Bloomreach recognizes users in a way that''s aligned with your system.
Use an anonymous string. Don''t use email or other personally identifiable information.
The example value shown here, <i>abc123</i>, is included for your convenience to send a request with <b>Try It</b>.
'
schema:
type: string
default: abc123
- name: start
in: query
description: 'The number of the first item on a page of results. For example, the first item on the first page is 0, making the start value also 0.
The maximum value is 10000.
'
example: 0
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"response\": {\n \"start\": 0,\n \"rows\": 2,\n \"docs\": [\n {\n \"pid\": \"prod1243\",\n \"url\": \"some url\",\n \"sale_price\": 34.2,\n \"title\": \"some title\"\n },\n {\n \"pid\": \"prod453\",\n \"url\": \"some url\",\n \"sale_price\": 124.2,\n \"title\": \"some title\"\n }\n ]\n },\n \"facet\": {\n \"category\": [\n {\n \"count\": 44,\n \"cat_id\": \"cat id\",\n \"cat_name\": \"home\",\n \"children\": [\n {\n \"count\": 21,\n \"cat_id\": \"cat id\",\n \"cat_name\": \"mens\",\n \"children\": [\n {\n \"count\": 12,\n \"cat_id\": \"cat_id\",\n \"cat_name\": \"men's shirts\",\n \"children\": null\n },\n {\n \"count\": 9,\n \"cat_id\": \"cat_id\",\n \"cat_name\": \"men's t-shirts\",\n \"children\": null\n }\n ]\n },\n ] \n },\n ],\n \"fields\":[\n {\n \"key\": \"Size\",\n \"type\": \"text\",\n \"value\": [],\n },\n {\n \"key\": \"Color\",\n \"type\": \"number\",\n \"value\":[]\n },\n {\n \"key\": \"sale_price_test\",\n \"type\": \"number_range\",\n \"value\": []\n }\n ],\n }\n \"metadata\": {\n \"widget\": {\n \"rid\": \"some id\",\n \"id\": \"some id\",\n \"type\": \"mlt\",\n \"description\": \"some text\",\n \"name\": \"some text\"\n },\n \"query\": {\n \"did_you_mean\": [\n \"black\",\n \"block\"\n ],\n \"modification\": {\n \"mode\": \"autoCorrectQuery\",\n \"value\": \"black\"\n }\n },\n \"response\": {\n \"personalized_results\": false,\n \"fallback\": \"mlt\"\n }\n }\n}"
schema:
type: object
properties:
response:
type: object
properties:
start:
type: integer
example: 0
default: 0
rows:
type: integer
example: 2
default: 0
docs:
type: array
items:
type: object
properties:
pid:
type: string
example: prod1243
url:
type: string
example: some url
sale_price:
type: number
example: 34.2
default: 0
title:
type: string
example: some title
facet:
type: object
properties:
ranges:
type: array
required: false
items:
type: object
properties:
key:
type: string
example: slider_price
value:
type: array
items:
type: object
properties:
count:
type: integer
example: 10
default: 0
start:
type: integer
example: 0
default: 0
end:
type: integer
example: 500
default: 0
fields:
type: array
items:
type: object
properties:
key:
type: string
example: colour
type:
type: string
enum:
- number
- number_range
- text
example: number_range
value:
type: array
items:
type: object
properties:
start:
type: integer
example: 1
end:
type: integer
example: 25
count:
type: integer
example: 231
default: 0
name:
type: string
example: black
category:
type: array
items:
type: object
properties:
count:
type: integer
example: 12
default: 0
cat_id:
type: string
example: some id
cat_name:
type: string
example: sale
children:
type: array
items:
type: string
example: empty_arry
query: {}
metadata:
type: object
properties:
widget:
type: object
properties:
rid:
type: string
example: some id
id:
type: string
example: some id
type:
type: string
example: mlt
description:
type: string
example: some text
name:
type: string
example: some text
query:
type: object
properties:
did_you_mean:
type: array
items:
type: string
example: black
modification:
type: object
properties:
mode:
type: string
example: autoCorrectQuery
value:
type: string
example: black
response:
type: object
properties:
personalized_results:
type: boolean
example: false
default: true
fallback:
type: string
example: mlt
'400':
description: '400'
content:
application/json:
examples:
Result:
value: Incorrect/Invalid query params.
'401':
description: '401'
content:
application/json:
examples:
Result:
value: An invalid auth-key is passed with the request.
'404':
description: '404'
content:
application/json:
examples:
Result:
value: 'The widget ID is not valid.
'
deprecated: false
components:
parameters:
Url:
name: url
in: query
description: 'The absolute URL of the page where the request is initiated. Don''t use a relative URL.
The example value shown here, <i>https://www.documentation-site.com</i>, is included for your convenience to send a request with <b>Try It</b>.
'
required: true
example: https://www.documentation-site.com
schema:
type: string
default: https://www.documentation-site.com
AccountId:
name: account_id
in: query
description: 'Your site''s numerical Bloomreach account ID.
Your Bloomreach representative gives your site''s account ID to you before or during your integration kickoff meeting.
The example value shown here, <i>6276</i>, is included for your convenience to send a request with <b>Try It</b>.
'
required: true
example: 6276
schema:
type: integer
format: int32
default: 6276
BrUid:
name: _br_uid_2
in: query
description: 'A first-party cookie created by the Bloomreach tracking pixel library (BrTrk).
This cookie creates a unique, anonymous identifier for every browser or device.
Use the default value provided, which is already encoded.
'
required: true
example: uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
schema:
type: string
default: uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
ContentInjection:
name: content_injection
in: query
description: "This parameter enables the [Personalized media in grid](https://documentation.bloomreach.com/discovery/docs/personalized-media-in-the-grid) feature.\n<br>If `true`, the API response includes media objects along with product results.\nThe content and positions of the media objects are governed by the [assets and media rules](https://documentation.bloomreach.com/discovery/docs/assets-and-media-rules) configured in the Bloomreach dashboard. \n"
required: false
example: true
schema:
type: boolean
DomainKey:
name: domain_key
in: query
description: 'Your site domain''s ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests.
This parameter identifies the specific site version when one account ID hosts multiple site versions with unique characteristics, such as language versions.
The example value shown here, <i>bloomreach_devdocs</i>, is included for your convenience to send a request with <b>Try It</b>.
'
required: true
example: bloomreach_devdocs
schema:
type: string
default: bloomreach_devdocs
RefUrl:
name: ref_url
in: query
description: 'The URL of the page or HTTP referrer where the request is started.
Required if you want to use [Targeting](https://documentation.bloomreach.com/discovery/docs/targeting).
'
schema:
type: string
ViewId:
name: view_id
in: query
description: 'A unique identifier for a specific view of your product catalog.
If you have multiple versions of your site, each with its own product catalog characteristics like product titles and prices, then add `view_id` to your call.
Bloomreach uses your `view_id` parameter value to display the right product information for your customers based on their individual site views.
You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog.
'
schema:
type: string
Fields:
name: fields
in: query
description: 'A comma-separated list of fields to be sent in the request.
Alternatively, you may configure the fields in the [Widget Configurator](https://documentation.bloomreach.com/discovery/docs/widget-configurator) in the Dashboard instead.
This parameter is required if not sent via the Dashboard.
'
schema:
type: string
RequestId:
name: request_id
in: query
description: 'An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits to enable click-tracking.
The `request_id` is also important for debugging.
'
required: true
example: abh3kjh1kjnd8
schema:
type: string
default: abh3kjh1kjnd8
WidgetId:
name: widget_id
in: path
description: 'The ID of the widget, which can be found in the [Widget Configurator](https://documentation.bloomreach.com/discovery/docs/widget-configurator) in the Dashboard.
The example value shown here, <i>1jwy7eg9</i>, is included for your convenience to send a request with <b>Try It</b>.
'
schema:
type: string
default: 1jwy7eg9
required: true
example: 1jwy7eg9
Filter:
name: filter
in: query
description: 'The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values.
Any facet that you want to filter must be in your feed. Attributes must be enabled and mapped by Bloomreach.
Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results.
You can filter results based on numeric ranges. For example, `&filter=(price:["100" TO "*"])`.
Note that a negative filter on ranges isn''t supported.
To provide multiple filters, send multiple filter parameters.
For example, `&filter=(price:["*" TO "100"])&filter=(color_groups: ("blue"))`.
'
schema:
type: string
Rows:
name: rows
in: query
description: 'The number of matching items to return per results page in the API response. The maximum value is 200.
The result size is used from the Dashboard if it isn''t sent in the API.
To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results.
'
schema:
type: integer
format: int32
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'HTTP Basic authentication using an API Key ID and API Secret.
For this workspace-scoped endpoint, use a workspace API key.
`Authorization: Basic <base64(APIKeyID:APISecret)>`
The API key must have the **Imports → Allow trigger imports**
permission enabled in Workspace settings → Access management →
API.
'