Constructor Configuration API
Authenticated configuration surface for facets, facet options, searchabilities, one-way synonyms, synonym groups, sort options, redirect rules, collections, quizzes and metadata overrides.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@constructor.io
title: Configuration
version: '0.1'
servers:
- url: https://ac.cnstrc.com
security: []
tags:
- name: Catalog
- name: Item groups
- name: Items
- name: Item statistics
- name: Variations
- name: Tasks
- name: Facets
- name: Synonyms
- name: Searchabilities
- name: Sort options
- name: Synonym groups
- name: Quizzes
- name: Collections
- name: Redirect rules
- name: Metadata overrides
paths:
/v1/facets:
get:
deprecated: true
tags:
- Facets
operationId: v1-facets-retrieve-facets
summary: Retrieve facet configurations (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(r)`.
Retrieve all facet configurations.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: num_results_per_page
in: query
schema:
title: Num Results Per Page
description: The number of results per page to return.
default: 100
minimum: 1
maximum: 1000
examples:
- 100
- 500
type: integer
required: false
- name: page
in: query
schema:
title: Page
description: The page of results to return.
minimum: 1
examples:
- 1
- 2
type: integer
required: false
- name: offset
in: query
schema:
title: Offset
description: The number of results to skip from the beginning. Cannot be used together with `page`.
minimum: 0
examples:
- 0
- 100
type: integer
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListGetResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(r)
post:
deprecated: true
tags:
- Facets
operationId: v1-facets-create-facet
summary: Create facet configuration (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Create facet configuration with specified `facet_name`.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListPostRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListPostResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
put:
deprecated: true
tags:
- Facets
operationId: v1-facets-create-or-replace-facets
summary: Create or replace facet configurations with options (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Create or replace facet configurations with their options. Replacing will delete the existing facet and recreate it with the provided data.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListPutRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListPutResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
patch:
deprecated: true
tags:
- Facets
operationId: v1-facets-update-facets
summary: Update facet configurations (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Update facet configurations with specified `facet_name`.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListPatchRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListPatchResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
/v1/facets/{facet_name}:
get:
deprecated: true
tags:
- Facets
operationId: v1-facets-retrieve-facet
summary: Retrieve facet configuration (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(r)`.
Retrieve facet configuration with specified `facet_name`.'
parameters:
- name: facet_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetGetResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(r)
put:
deprecated: true
tags:
- Facets
operationId: v1-facets-replace-facet
summary: Replace facet configuration (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Replace facet configuration with specified `facet_name`. This will overwrite all other configurations you may have defined for the facet group, resetting them to their defaults. This includes all facet option configurations you may have defined.'
parameters:
- name: facet_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetPutRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetPutResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'409':
description: Conflict
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
patch:
deprecated: true
tags:
- Facets
operationId: v1-facets-update-facet
summary: Update facet configuration (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Partially update facet configuration with specified `facet_name`.'
parameters:
- name: facet_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetPatchRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetPatchResponse'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/FacetPatchResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'409':
description: Conflict
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
delete:
deprecated: true
tags:
- Facets
operationId: v1-facets-delete-facet
summary: Delete facet configuration (Deprecated)
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Delete facet configuration with specified `facet_name`. This does not delete the facet from items in your index you may have uploaded previously. Once a facet group''s configuration is deleted, all configurations will return to their default values. This includes all facet option configurations (display name, position, etc) you may have defined for the facet group.'
parameters:
- name: facet_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetDeleteResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
/v2/facets:
get:
tags:
- Facets
operationId: v2-facets-retrieve-facets
summary: Retrieve facet configurations
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(r)`.
Retrieve all facet configurations.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: num_results_per_page
in: query
schema:
title: Num Results Per Page
description: The number of results per page to return.
default: 100
minimum: 1
maximum: 1000
examples:
- 100
- 500
type: integer
required: false
- name: page
in: query
schema:
title: Page
description: The page of results to return.
minimum: 1
examples:
- 1
- 2
type: integer
required: false
- name: offset
in: query
schema:
title: Offset
description: The number of results to skip from the beginning. Cannot be used together with `page`.
minimum: 0
examples:
- 0
- 100
type: integer
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2GetResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(r)
post:
tags:
- Facets
operationId: v2-facets-create-facet
summary: Create facet configuration
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Create facet configuration with specified `facet_name`.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2PostRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2PostResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'409':
description: Conflict
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
put:
tags:
- Facets
operationId: v2-facets-create-or-replace-facets
summary: Create or replace facet configurations
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Create or replace facet configurations. Replacing will overwrite all other configurations you may have defined for the facet group, resetting them to their defaults, except facet options - they will not be affected.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2PutRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2PutResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'409':
description: Conflict
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
patch:
tags:
- Facets
operationId: v2-facets-update-facets
summary: Update facet configurations
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(w)`.
Update facet configurations.'
parameters:
- name: key
in: query
schema:
title: Key
description: The key of the index to use.
maxLength: 100
minLength: 1
examples:
- key_K2pX7vBnU0bgA5xp
type: string
required: true
- name: section
in: query
schema:
title: Section
description: The section of the index to use. Defaults to `Products`.
maxLength: 100
minLength: 1
examples:
- Products
- Search Suggestions
type: string
required: false
- name: c
in: query
schema:
title: C
description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
maxLength: 100
minLength: 1
examples:
- cio-js-2.90
- cio-ios-1.0
type: string
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2PatchRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacetListV2PatchResponse'
'400':
description: Validation Error
'401':
description: Credentials are not passed or action is forbidden.
'403':
description: The supplied token does not have the required permissions.
'404':
description: Not Found
'409':
description: Conflict
'429':
description: Rate limit breached
security:
- http_basic_auth: []
- http_bearer_auth:
- facets(w)
/v2/facets/{facet_name}:
get:
tags:
- Facets
operationId: v2-facets-retrieve-facet
summary: Retrieve facet configuration
description: '**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `facets(r)`.
Retrieve facet configuration with specified `facet_name`.'
parameters:
- name: facet_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: key
in: query
schem
# --- truncated at 32 KB (584 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/constructorio/refs/heads/main/openapi/constructorio-configuration-openapi.yml