Bloomreach Bestseller API v1 API

openapi: 3.1.0
info:
  title: Workspace Imports Autosuggest API v2 Bestseller API v1 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: Bestseller API v1
paths:
  /:
    get:
      tags:
      - Bestseller API v1
      summary: Get bestseller products
      description: The Bestseller API returns the products likely to generate the most revenue. The algorithm uses a combination of RPV, ATCs and Views, combined in order to maximize revenue.
      operationId: bestseller-api
      parameters:
      - 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. <br><br> Use the default value provided, which is already encoded.
        required: true
        example: '{{ br_uid_2 }}'
        schema:
          type: string
          default: uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
      - 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. <br><br> The example value shown here, <i>6702</i>, is included for your convenience to send a request with <b>Try It</b>.
        required: true
        example: '{{ account_id }}'
        schema:
          type: integer
          format: int32
          default: 6702
      - name: auth_key
        in: query
        description: The Bloomreach-provided authentication key for the Bloomreach account that's sending the request. <br><br> Pass the auth_key with an empty value in client-side calls.  The auth_key value is a private authorization key. If you include your valid auth_key value in client-side calls, then you inadvertently expose that private information to everybody.
        example: '{{ auth_key }}'
        schema:
          type: string
      - name: callback
        in: query
        description: Indicates whether to return data wrapped in the function for cross-origin requests. <br><br> For server-side requests, use the value **br_server**. For native-app requests, use the value **br_app**.
        schema:
          type: string
          enum:
          - br_server
          - br_app
      - 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 the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions.
        required: true
        example: '{{ domain_key }}'
        schema:
          type: string
          default: example_com
      - name: fl
        in: query
        description: The attributes that you want returned in your API response, such as product IDs and prices. <br><br> All fl parameters for Bestseller requests must include **pid** as one of their values. Any attribute from your product feed may be used as a value for fl. <br><br> Multiple values should be comma separated, such as **fl=pid,price**.
        required: true
        example: pid,url,description
        schema:
          type: string
          default: pid,url,description
      - name: fq
        in: query
        description: The fq parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. <br><br> Any facet that you want to filter must be in your feed.  Read more about using the fq parameter in the "Simple Filtering" section in the [Faceting and filtering page](ref:faceting-and-filtering). <br><br> You can [configure Attributes](doc:understanding-feed-configuring-attributes) from the Catalog Management Tab. Configure which attributes in your content feed you want to apply as filters to search results.
        schema:
          type: string
      - name: ref_url
        in: query
        description: The URL of the page or HTTP referrer where the request is started.
        required: true
        example: '{{ ref_url }}'
        schema:
          type: string
          default: https://example.com
      - 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. <br><br> Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter test as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem.
        required: true
        example: 1234567891234
        schema:
          type: string
          default: 1703497216731
      - name: request_type
        in: query
        description: The type of API request. Value should be **search** for Bestseller requests.
        required: true
        example: search
        schema:
          type: string
          enum:
          - search
          default: search
      - name: rows
        in: query
        description: The number of matching items to return per results page in the API response. The maximum value is 200. <br><br> To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results.
        required: true
        example: 10
        schema:
          type: integer
          format: int32
      - name: search_type
        in: query
        description: The type of search. Value should be **bestseller** for Bestseller requests.
        required: true
        example: bestseller
        schema:
          type: string
          enum:
          - bestseller
          default: bestseller
      - 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. <br><br> The maximum value is 10000.
        required: true
        example: 0
        schema:
          type: integer
          format: int32
          default: 0
      - name: title
        in: query
        description: The title or name of the product.
        schema:
          type: string
      - name: url
        in: query
        description: The absolute URL of the page where the request is initiated. Do not use a relative URL.
        required: true
        example: '{{ url }}'
        schema:
          type: string
          default: https://www.documentation-site.com
      - name: user_id
        in: query
        description: The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way.  The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. <br><br> Use an anonymous string. Don't use email or other personally identifiable information. <br><br> If you do not track users this way, then omit this field.
        schema:
          type: string
      - 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 their own product catalog characteristics like product titles and prices, then add view_id to your call. <br><br> 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
      deprecated: false
components:
  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.

        '