v1

latestOpenAPI 3.1.02026-07-241765501.1 MB

Facets

Retrieve facet configuration

🔐 This endpoint requires HTTP authentication (either Basic or Bearer). For authenticating with Bearer token, required scopes are: facets(r).

Retrieve facet configuration with specified facet_name.

get/v2/facets/{facet_name}

Path parameters

facet_namestring required

Example:Brand

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

cstring

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

Example:cio-js-2.90

Response

namestring

The facet name used to refer to the facet in your catalog. Must be unique inside the section and key.

path_in_metadatastring

The path in metadata of each item where this facet is present. Must be unique inside the section and key.

type'multiple' | 'range' | 'hierarchical'

display_namestring

The name of the facet to present to end users. Default value is null, in which case the name will be presented.

sort_order'relevance' | 'value' | 'num_matches'

sort_descendingboolean

true if this facet group's options should be sorted in descending order, false to sort ascending. Default value is true if sort_order is relevance or num_matches and false for value. Setting sort_order: relevance will set sort_descending: true for POST, PUT, PATCH endpoints if sort_descending is not explicitly set in the request.

range_type'static'

range_format'boundaries' | 'options'

range_inclusive'above' | 'below'

match_type'any' | 'all' | 'none'

positioninteger

Used to slot facet groups to fixed positions. Must be >= 1. Default value is null.

hiddenboolean

Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive.

protectedboolean

Specifies whether the facet is protected from users. Setting this to true will require authentication to view the facet.

countableboolean

Specifies whether counts for each facet option should be calculated and shown in the response. Setting this to false will skip counting these options, improving performance for facets with high cardinality.

options_limitinteger

Maximum number of options of facet type multiple to return in search responses. If absent, the default limit is applied.

dataobject

Dictionary with any extra facet data. Default value is {} (empty dictionary).

created_atstring date-time required

Facet creation date and time in ISO 8601 format

updated_atstring date-time

Last facet update date and time in ISO 8601 format.

Example response

{
  "name": "Brand",
  "path_in_metadata": "data.brand",
  "display_name": "Brand Name",
  "sort_descending": true,
  "position": 1,
  "countable": true,
  "data": {
    "key": "value"
  }
}