Constructor Searchandising API
Merchandising-rule surface for refined queries, refined filters, refined collections, refined tags, campaigns and facet-rule campaigns across search, browse and collections.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@constructor.io
title: Searchandising
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: Facets v2
- name: Synonyms
- name: Searchabilities
- name: Searchabilities v2
- name: Sort options
- name: Synonym groups
- name: Quizzes
- name: Collections
- name: Redirect rules
- name: Metadata overrides
- name: Searchandising for Browse
- name: Searchandising for Collections
- name: Searchandising for Search
- name: Searchandising by User Request Data
- name: Searchandising campaigns
- name: Facet campaigns
paths:
/v1/refined_filters:
get:
tags:
- Searchandising for Browse
operationId: v1-searchandising-retrieve-refined-filters
summary: Retrieve refined filters
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.refined_filters(r)`, `searchandising.refined_filters(r)`.
Retrieve all refined filters.'
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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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: filter_names_to_exclude
in: query
schema:
title: Filter Names To Exclude
description: A list of filter names to exclude from results.
type: array
items:
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: 20
minimum: 1
maximum: 100
examples:
- 20
- 50
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: sort_by
in: query
schema:
title: Sort By
description: The attribute to sort by.
default: id
examples:
- id
- created_at
enum:
- id
- created_at
- updated_at
- last_updated_internally
- last_updated_externally
type: string
required: false
- name: sort_order
in: query
schema:
description: The order by which results should be sorted. Only valid in conjunction with `sort_by`.
default: ascending
examples:
- ascending
- descending
allOf:
- $ref: '#/components/schemas/SortOrderType'
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
- name: segments
in: query
schema:
title: Segments
description: Filtering conditions by segment type
allOf:
- $ref: '#/components/schemas/SegmentsFilter'
required: false
- name: filter
in: query
schema:
title: Filter
description: A list of filters to retrieve
type: object
additionalProperties:
type: array
items:
type: string
required: false
style: deepObject
explode: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefinedFilterListGetResponse'
'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.refined_filters(r)
- searchandising.refined_filters(r)
/v1/refined_filters/{filter_name}/{filter_value}:
get:
tags:
- Searchandising for Browse
operationId: v1-searchandising-retrieve-refined-filter
summary: Retrieve refined filter
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.refined_filters(r)`, `searchandising.refined_filters(r)`.
Retrieve a refined filter.'
parameters:
- name: filter_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: filter_value
in: path
required: true
schema:
type: string
examples:
- Nike
- Red
- 10-20
- 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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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: filter_names_to_exclude
in: query
schema:
title: Filter Names To Exclude
description: A list of filter names to exclude from results.
type: array
items:
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: 20
minimum: 1
maximum: 100
examples:
- 20
- 50
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: sort_by
in: query
schema:
title: Sort By
description: The attribute to sort by.
default: id
examples:
- id
- created_at
enum:
- id
- created_at
- updated_at
- last_updated_internally
- last_updated_externally
type: string
required: false
- name: sort_order
in: query
schema:
description: The order by which results should be sorted. Only valid in conjunction with `sort_by`.
default: ascending
examples:
- ascending
- descending
allOf:
- $ref: '#/components/schemas/SortOrderType'
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
- name: segments
in: query
schema:
title: Segments
description: Filtering conditions by segment type
allOf:
- $ref: '#/components/schemas/SegmentsFilter'
required: false
- name: filter
in: query
schema:
title: Filter
description: A list of filters to retrieve
type: object
additionalProperties:
type: array
items:
type: string
required: false
style: deepObject
explode: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefinedFilterGetResponse'
'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.refined_filters(r)
- searchandising.refined_filters(r)
put:
tags:
- Searchandising for Browse
operationId: v1-searchandising-create-or-replace-refined-filter
summary: Create or replace refined filter
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: `searchandising.refined_filters(w)`, `facets.refined_filters(w)`.
Create or replace a refined filter. It will replace all existing rules associated with the specified `filter_name` and `filter_value` if there are any. It will also flip `allow_automatic_rules` to `true` (which is default) if attribute''s value isn''t submitted in the request.'
parameters:
- name: filter_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: filter_value
in: path
required: true
schema:
type: string
examples:
- Nike
- Red
- 10-20
- 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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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/RefinedFilterPutBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefinedFilterPutResponse'
'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:
- searchandising.refined_filters(w)
- facets.refined_filters(w)
patch:
tags:
- Searchandising for Browse
operationId: v1-searchandising-update-refined-filter
summary: Update refined filter
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: `searchandising.refined_filters(w)`.
Update a refined filter. It will update only the fields that are present in the request.'
parameters:
- name: filter_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: filter_value
in: path
required: true
schema:
type: string
examples:
- Nike
- Red
- 10-20
- 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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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/RefinedFilterPatchBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefinedFilterPatchResponse'
'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:
- searchandising.refined_filters(w)
delete:
tags:
- Searchandising for Browse
operationId: v1-searchandising-delete-refined-filter
summary: Delete refined filter
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: `searchandising.refined_filters(w)`.
Delete a refined filter.'
parameters:
- name: filter_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: filter_value
in: path
required: true
schema:
type: string
examples:
- Nike
- Red
- 10-20
- 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/RefinedFilterDeleteResponse'
'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:
- searchandising.refined_filters(w)
/v1/refined_filters/{filter_name}/{filter_value}/rules:
get:
tags:
- Searchandising for Browse
operationId: v1-searchandising-retrieve-refined-filter-rules
summary: Retrieve refined filter rules
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: `searchandising.refined_filters(r)`.
Retrieve all refined filter rules.'
parameters:
- name: filter_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: filter_value
in: path
required: true
schema:
type: string
examples:
- Nike
- Red
- 10-20
- 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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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: filters
in: query
schema:
$ref: '#/components/schemas/RefinedFilterRuleFilters'
required: false
style: deepObject
explode: true
- name: num_results_per_page
in: query
schema:
title: Num Results Per Page
description: The number of results per page to return.
default: 20
minimum: 1
maximum: 100
examples:
- 20
- 50
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: sort_by
in: query
schema:
title: Sort By
description: The attribute to sort by.
default: id
enum:
- id
- created_at
- updated_at
type: string
required: false
- name: sort_order
in: query
schema:
description: The order by which results should be sorted. Only valid in conjunction with `sort_by`.
default: ascending
allOf:
- $ref: '#/components/schemas/SortOrderType'
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/RefinedFilterRuleListGetResponse'
'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:
- searchandising.refined_filters(r)
delete:
tags:
- Searchandising for Browse
operationId: v1-searchandising-delete-refined-filter-rules
summary: Delete refined filter rules
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.refined_filters(w)`, `searchandising.refined_filters(w)`.
Delete all refined filter rules.'
parameters:
- name: filter_name
in: path
required: true
schema:
type: string
examples:
- Brand
- Color
- Price
- name: filter_value
in: path
required: true
schema:
type: string
examples:
- Nike
- Red
- 10-20
- 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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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:
'204':
description: No Content
'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.refined_filters(w)
- searchandising.refined_filters(w)
/v1/refined_collections:
get:
tags:
- Searchandising for Collections
operationId: v1-searchandising-retrieve-refined-collections
summary: Retrieve refined collections
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: `searchandising.refined_collections(r)`.
Retrieve all refined collections.'
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: response_section
in: query
schema:
description: The section of the response to apply rules to, such as `results` or `facets`.
default: results
allOf:
- $ref: '#/components/schemas/RefinedObjectRuleResponseSection'
required: false
- 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: filter_names_to_exclude
in: query
schema:
title: Filter Names To Exclude
description: A list of filter names to exclude from results.
type: array
items:
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: 20
minimum: 1
maximum: 100
examples:
- 20
- 50
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: sort_by
in: query
schema:
title: Sort By
description: The attribute to sort by.
default: id
examples:
- id
- created_at
enum:
- id
- created_at
- updated_at
- last_updated_internally
- last_updated_externally
type: string
required: false
- name: sort_order
in: query
schema:
description: The order by which results should be sorted. Only valid in conjunction with `sort_by`.
default: ascending
examples:
- ascending
- descending
allOf:
- $ref: '#/components/schemas/SortOrderType'
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
- name: segments
in: query
schema:
title: Segments
description: Filtering conditions by segment type
allOf:
- $ref: '#/components/schemas/SegmentsFilter'
required: false
- name: filter
in: query
schema:
title: Filter
description: A list of filters to retrieve
type: object
additionalProperties:
type: array
items:
type: string
required: false
style: deepObject
explode: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefinedCollectionListGetResponse'
'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 br
# --- truncated at 32 KB (266 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/constructorio/refs/heads/main/openapi/constructorio-searchandising-openapi.yml