v1

latestOpenAPI 3.1.02026-07-241765501.1 MB

Browse facets

Retrieve facet options (values) by facet name

Retrieve facet options for end users.

get/browse/facet_options

Query parameters

keystring required

The key of the index to use.

Example:key_K2pX7vBnU0bgA5xp

sectionstring

The section of the index to use. Defaults to Products.

Example:Products

num_results_per_pageinteger

The number of results per page to return.

Example:100000

pageinteger

The page of results to return.

Example:1

offsetinteger

The number of results to skip from the beginning. Cannot be used together with page.

nowstring date-time

A date time representing the current moment in time when applying filtering by product age. Used to emulate "past/future" requests. Requires authentication.

Example:2024-01-15T10:30:00Z

show_hidden_facetsboolean

A flag to return all facets configured as hidden in response.facets.

hidden_facetsstring[]

A list of specific hidden facets to return in the response. Unlike show_hidden_facets this parameter allows the request to control which hidden facets are returned. Used to return facets for a particular store or user segment.

show_hidden_facet_optionsboolean

A flag to return all hidden facets options in the response.

show_protected_facetsboolean

A flag to return all protected facets in the response. Requires authentication.

show_internal_facetsboolean

{
  "hidden_facets": [
    "store_id"
  ]
}

origin_referrerstring

The url or app location where the request originated.

Example:https://example.com/search

cstring

The ID of the client and version that the request is coming from, such as cio-js-2.90.

Example:cio-js-client-2.35.2

facet_namestring required

The name of the facet

Example:color

usstring[]

A customer defined context (such as vip-club-member) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple us arguments.

[
  "vip-member"
]

uistring

A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.

Example:customer-user-id-456

sinteger

An integer representing the users session number (starting with 1), incremented after a 30 minute period of inactivity.

Example:1

istring

A globally unique identifier for the user browser (or mobile application instance) making the request.

Example:user-device-id-123

Response

requestobject required

The request arguments how they were interpreted by the API. This field is of arbitrary type, ie it doesn't have a guaranteed schema, and data from it shouldn't be used programmatically, it is for debugging purposes only.

result_idstring

Example response

{
  "response": {
    "facets": [
      {
        "options": [
          {
            "value": "Red",
            "value_alias": "blue",
            "replace_value_alias": true,
            "display_name": "Bright Red",
            "position": 1,
            "data": {
              "hex": "#FF0000"
            }
          }
        ],
        "name": "Brand",
        "display_name": "Brand Name",
        "sort_descending": true,
        "position": 1,
        "options_limit": 300,
        "data": {
          "key": "value"
        }
      }
    ]
  }
}