Sign in

v1

latestOpenAPI 3.1.02026-07-241765501.1 MB
Facets

Create facet configuration (Deprecated)

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

Create facet configuration with specified facet_name.

post/v1/facets

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

Request body

OR
OR

Example request

{
  "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"
  }
}

Response

OK

namestring

The facet name used to refer to the facet in your catalog. 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. 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

{
  "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,
  "data": {
    "key": "value"
  }
}