Constructor Searchandising API

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