Constructor.io Search results API

openapi: 3.2.0
info:
  contact:
    email: support@constructor.io
  title: Search results API
  version: '0.1'
servers:
- url: https://ac.cnstrc.com
security: []
tags:
- name: Search results
paths:
  /v1/search/{search_query}:
    get:
      tags:
      - Search results
      operationId: v1-search-get-search-results
      summary: Retrieve by query
      description: Retrieve AI optimized search results for products (or optionally other sections) by search query.
      parameters:
      - name: search_query
        in: path
        required: true
        schema:
          type: string
          format: path
          examples:
          - red shoes
          - lipstick
      - name: key
        in: query
        schema:
          description: The key of the index to use.
          examples:
          - key_K2pX7vBnU0bgA5xp
          maxLength: 100
          minLength: 1
          title: Key
          type: string
        required: true
      - name: section
        in: query
        schema:
          description: The section of the index to use. Defaults to `Products`.
          examples:
          - Products
          - Search Suggestions
          title: Section
          maxLength: 100
          minLength: 1
          type: string
        required: false
      - name: filters
        in: query
        schema:
          description: Any number of filtering criteria (accessible to end users) used to narrow the result set, such as `color=blue` or `group_id=sandals` or `price=100-200`. Facets and Item Groups and Collections can be used as filters. If `filter_value` has the form `<min>-<max>`, it is interpreted as a range. Filters with the same key are ORed together and filters with different keys are ANDed together by default. Only results that match the filters are returned. Boolean values are serialized with the first letter capitalized (e.g., `True` / `False`) as a convention.
          examples:
          - color:
            - red
            - blue
            price:
            - 100-200
          allOf:
          - $ref: '#/components/schemas/Filters'
          title: Filters
        required: false
        style: deepObject
        explode: true
      - name: filter_match_types
        in: query
        schema:
          description: 'An object specifying whether results must match `all`, `any` or `none` of a given filter when multiple options of the same facet (e.g: color: yellow & blue) are selected.'
          examples:
          - color: any
            size: all
          title: Filter Match Types
          additionalProperties:
            $ref: '#/components/schemas/FilterMatchType'
          type: object
        required: false
        style: deepObject
        explode: true
      - name: pre_filter_expression
        in: query
        schema:
          description: A JSON-encoded [filter expression](/reference/shared-filter-expressions) containing any number of filters (inaccessible to end users) used to narrow the result set. Applied before user-selected `filters`. Only items that match this expression are  considered in facet counts. Only results that match the filters are returned. [Read more](/reference/shared-pre-filter-expressions).
          examples:
          - '{"and":[{"name":"brand","value":"Nike"}]}'
          allOf:
          - $ref: '#/components/schemas/DictOrJsonStringWithDict'
          title: Pre Filter Expression
        required: false
      - name: num_results_per_page
        in: query
        schema:
          default: 20
          description: The number of results per page to return.
          examples:
          - 20
          - 24
          title: Num Results Per Page
          maximum: 200
          minimum: 1
          type: integer
        required: false
      - name: page
        in: query
        schema:
          description: The page of results to return.
          examples:
          - 1
          title: Page
          minimum: 1
          type: integer
        required: false
      - name: offset
        in: query
        schema:
          description: The number of results to skip from the beginning. Cannot be used together with `page`.
          examples:
          - 0
          title: Offset
          minimum: 0
          type: integer
        required: false
      - name: sort_by
        in: query
        schema:
          default: relevance
          description: The method to sort results by. The default value `relevance` sorts by Constructor's attractiveness & personalization algorithms and is reserved. Alternative sort criteria can be configured using the [Sort options API](/reference/v1-sort-options-create-or-replace-sort-options).
          examples:
          - relevance
          title: Sort By
          type: string
        required: false
      - name: sort_order
        in: query
        schema:
          default: descending
          description: The order by which results should be sorted. Only valid in conjunction with `sort_by`.
          examples:
          - descending
          allOf:
          - $ref: '#/components/schemas/SortOrderType'
        required: false
      - name: now
        in: query
        schema:
          description: A date time representing the current moment in time when applying filtering by product age. Used to emulate "past/future" requests. Requires authentication.
          examples:
          - '2024-01-15T10:30:00Z'
          title: Now
          format: date-time
          type: string
        required: false
      - name: variations_map
        in: query
        schema:
          description: A JSON string containing a instructions on how to map item variation data in the response (typically used for swatches). More details, including the exact schema for this value can be found [here](/reference/shared-variations-mapping)
          examples:
          - '{"group_by":[{"name":"color","field":"data.color"}],"values":{"price":{"aggregation":"min","field":"data.price"}},"dtype":"array"}'
          format: json
          title: Variations Map
          type: string
          allOf:
          - $ref: '#/components/schemas/VariationsMap'
        required: false
      - name: fmt_options
        in: query
        schema:
          description: An object containing options to format different aspect of the response.
          allOf:
          - $ref: '#/components/schemas/FmtOptions'
          title: Fmt Options
        required: false
        style: deepObject
        explode: true
      - name: qs
        in: query
        schema:
          description: A JSON-encoded query string. Any query parameters listed for this endpoint can be serialized into a JSON string and parsed thru the `qs` param.
          format: json
          title: Qs
          type: string
        required: false
      - name: origin_referrer
        in: query
        schema:
          description: The url or app location where the request originated.
          examples:
          - https://example.com/search
          title: Origin Referrer
          type: string
        required: false
      - name: c
        in: query
        schema:
          description: The ID of the client and version that the request is coming from, such as `cio-js-2.90`.
          examples:
          - cio-js-client-2.35.2
          title: C
          maxLength: 100
          minLength: 1
          type: string
        required: false
      - name: us
        in: query
        schema:
          description: A customer defined context (such as `vip-club-member`) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple `us` arguments.
          title: us
          items:
            minLength: 1
            type: string
            examples:
            - vip-member
            - us-east-region
          type: array
        required: false
      - name: ui
        in: query
        schema:
          description: A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.
          examples:
          - customer-user-id-456
          title: Ui
          type: string
        required: false
      - name: s
        in: query
        schema:
          description: An integer representing the users session number (starting with `1`), incremented after a 30 minute period of inactivity.
          examples:
          - 1
          title: S
          type: integer
        required: false
      - name: i
        in: query
        schema:
          description: A globally unique identifier for the user browser (or mobile application instance) making the request.
          examples:
          - user-device-id-123
          title: I
          type: string
        required: false
      - name: lang
        in: query
        schema:
          description: 'A specification of the user query language. When provided, this parameter enables language-specific processing such as stemming to improve relevance and recall. '
          examples:
          - en
          title: Lang
          enum:
          - ar
          - ca
          - cs
          - da
          - de
          - el
          - en
          - es
          - et
          - eu
          - fi
          - fr
          - ga
          - he
          - hi
          - hu
          - hy
          - id
          - it
          - lt
          - lv
          - ne
          - nl
          - 'no'
          - pl
          - pt
          - ro
          - ru
          - sk
          - sr
          - sv
          - ta
          - tr
          - yi
          type: string
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchGetResponse'
        '400':
          description: Validation Error
      security: []
components:
  schemas:
    VariationsMapNot:
      additionalProperties: false
      properties:
        not_:
          type: object
          title: Not
      required:
      - not_
      title: VariationsMapNot
      type: object
    RangeFacet:
      additionalProperties: false
      properties:
        type:
          description: If a facet is of type `range`, then no facet options are provided. Instead a `min` and `max` value is provided to specify the range of values that can be sent in `filters`.
          title: Type
          type: string
          enum:
          - range
        name:
          description: The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. `filters[name]=value`
          title: Name
          type: string
        display_name:
          description: The name of the facet as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`.
          title: Display Name
          type: string
        hidden:
          description: The boolean value saying whether facet is available for interaction.
          title: Hidden
          type: boolean
        data:
          description: Object containing custom data associated with this facet. An empty object (`{}`) if no data is currently associated with this facet.
          title: Data
          type: object
        status:
          description: Specifies the selected facet value range. If no range is selected the field will be omitted.
          allOf:
          - $ref: '#/components/schemas/RangeFacetStatus'
          title: Status
        min:
          anyOf:
          - type: number
          - type: integer
          - enum:
            - -inf
            - +inf
            - inf
            type: string
          description: Minimum facet value of the result items.
          title: Min
        max:
          anyOf:
          - type: number
          - type: integer
          - enum:
            - -inf
            - +inf
            - inf
            type: string
          description: Maximum facet value of the result items.
          title: Max
      required:
      - type
      - name
      - display_name
      - hidden
      - data
      title: Range facet
      type: object
    ResultVariation:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ResultData'
        value:
          title: Value
          type: string
      required:
      - data
      - value
      title: ResultVariation
      type: object
    VariationsMapSimpleAggregation:
      properties:
        aggregation:
          enum:
          - first
          - all
          - distinct
          - min
          - max
          - field_count
          title: Aggregation
          type: string
        field:
          minLength: 1
          title: Field
          type: string
      required:
      - aggregation
      - field
      title: VariationsMapSimpleAggregation
      type: object
    ResultSourceValue:
      additionalProperties: false
      properties:
        count:
          description: Number of results returned from their respective sources
          minimum: 0
          title: Count
          type: integer
      required:
      - count
      title: ResultSourceValue
      type: object
    SearchandizedResult:
      additionalProperties: false
      properties:
        value:
          description: Name of the matched item or variation (if variations are defined).
          title: Value
          type: string
        matched_terms:
          description: All terms within the item matching the user's query (regardless of whether misspelled).
          items:
            type: string
          title: Matched Terms
          type: array
        data:
          $ref: '#/components/schemas/ResultData'
        variations:
          description: An array of this item's variations matching user's query.
          maxItems: 50
          title: Variations
          items:
            $ref: '#/components/schemas/ResultVariation'
          type: array
        variations_map:
          anyOf:
          - items: {}
            type: array
          - additionalProperties: true
            type: object
          description: Variations data in the format requested by `variations_map` query parameter.
          title: Variations Map
        variation_slice:
          description: If variation slicing is enabled, this represents the variation slice of the item.
          title: Variation Slice
          additionalProperties:
            items:
              type: string
            type: array
          type: object
        is_slotted:
          description: '`true` if the current product is slotted as a result of searchandizing.'
          title: Is Slotted
          type: boolean
        labels:
          description: A set of miscellaneous properties of this result. For example, it can indicate whether a slotted result is advertised or promoted.
          title: Labels
          type: object
      required:
      - value
      - matched_terms
      - data
      - is_slotted
      - labels
      title: SearchandizedResult
      type: object
    RedirectData:
      properties:
        url:
          description: Target URL of the redirect.
          title: Url
          type: string
      required:
      - url
      title: RedirectData
      type: object
    SortOption:
      additionalProperties: false
      properties:
        display_name:
          description: The name of the sortable field as it is displayed to end users.
          title: Display Name
          type: string
        status:
          description: '`selected` if this option is selected in the current search request, empty string otherwise.'
          enum:
          - selected
          - ''
          title: Status
          type: string
        sort_by:
          description: The attribute to sort by, and the value of the sort_by query parameter in the search request.
          title: Sort By
          type: string
        sort_order:
          description: The value of this attribute should be passed to the `sort_order` query string parameter in the search request when this option is selected.
          allOf:
          - $ref: '#/components/schemas/SortOrderType'
        hidden:
          description: '`true` if this sort option is hidden, `false` otherwise.'
          title: Hidden
          type: boolean
      required:
      - display_name
      - status
      - sort_by
      - sort_order
      - hidden
      title: SortOption
      type: object
    Path:
      additionalProperties: false
      properties:
        id:
          description: The ID of the group.
          title: Id
          type: string
        display_name:
          description: The name of the group as it is displayed to end users.
          title: Display Name
          type: string
      required:
      - id
      title: Path
      type: object
    VariationsMapGrouping:
      properties:
        name:
          pattern: ^\w+([ ]?[\w]+)*$
          title: Name
          type: string
        field:
          minLength: 1
          title: Field
          type: string
      required:
      - name
      - field
      title: VariationsMapGrouping
      type: object
    VariationsMapSingleFilter:
      additionalProperties: false
      properties:
        field:
          description: Path to a metadata field (dot-separated)
          minLength: 1
          title: Field
          type: string
        value:
          anyOf:
          - type: boolean
          - type: integer
          - type: number
          - type: string
          description: The value of this field to filter by
          title: Value
      required:
      - field
      - value
      title: VariationsMapSingleFilter
      type: object
    SingleOrMultipleFacet:
      additionalProperties: false
      properties:
        type:
          description: 'If a facet is of type `single`, then only one of the options may be selected (e.g: display as radio button). If the type is `multiple`, then multiple options may be selected (e.g: display as checkboxes).'
          enum:
          - single
          - multiple
          title: Type
          type: string
        name:
          description: The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. `filters[name]=value`
          title: Name
          type: string
        display_name:
          description: The name of the facet as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`.
          title: Display Name
          type: string
        hidden:
          description: The boolean value saying whether facet is available for interaction.
          title: Hidden
          type: boolean
        data:
          description: Object containing custom data associated with this facet. An empty object (`{}`) if no data is currently associated with this facet.
          title: Data
          type: object
        options:
          description: An array of possible facet values matching this search. By default, facet options are sorted by relevance. Number of options is limited, by default, to 500. But the limit can be configured per [facet](/reference/v1-facets-create-facet) key.
          title: Options
          items:
            $ref: '#/components/schemas/FacetOption'
          type: array
      required:
      - type
      - name
      - display_name
      - hidden
      - data
      title: Single or Multiple facet
      type: object
    ResultFacet:
      additionalProperties: false
      properties:
        name:
          title: Name
          type: string
        values:
          items:
            anyOf:
            - type: number
            - type: integer
            - type: string
            - type: boolean
          title: Values
          type: array
      required:
      - name
      - values
      title: ResultFacet
      type: object
    Feature:
      additionalProperties: false
      properties:
        display_name:
          description: The name of the features as it is displayed to end users.
          title: Display Name
          type: string
        enabled:
          description: Displays the enabled status of the feature.
          title: Enabled
          type: boolean
        feature_name:
          description: The name of the feature.
          title: Feature Name
          type: string
        variant:
          description: Displays the variant of this feature if there are any.
          allOf:
          - $ref: '#/components/schemas/FeatureVariant'
          title: Variant
      required:
      - display_name
      - enabled
      - feature_name
      title: Feature
      type: object
    ResultGroup:
      additionalProperties: false
      properties:
        group_id:
          description: The ID of the group.
          title: Group Id
          type: string
        display_name:
          description: The name of the group as it is displayed to end users.
          title: Display Name
          type: string
        path:
          description: The path of `group_id`s above this group. `/great-grandparent/grandparent/parent/`
          examples:
          - /great-grandparent/grandparent/parent/
          title: Path
          type: string
        path_list:
          description: An array of groups constituting the path
          items:
            $ref: '#/components/schemas/Path'
          title: Path List
          type: array
      required:
      - group_id
      - path
      - path_list
      title: ResultGroup
      type: object
    HierarchicalFacet:
      additionalProperties: false
      properties:
        type:
          title: Type
          type: string
          enum:
          - hierarchical
        name:
          description: The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. `filters[name]=value`
          title: Name
          type: string
        display_name:
          description: The name of the facet as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`.
          title: Display Name
          type: string
        hidden:
          description: The boolean value saying whether facet is available for interaction.
          title: Hidden
          type: boolean
        data:
          description: Object containing custom data associated with this facet. An empty object (`{}`) if no data is currently associated with this facet.
          title: Data
          type: object
        options:
          description: An array of possible facet values matching this search. By default, facet options are sorted by relevance.
          title: Options
          items:
            $ref: '#/components/schemas/HierarchicalFacetOption'
          type: array
      required:
      - type
      - name
      - display_name
      - hidden
      - data
      title: Hierarchical facet
      type: object
    RangeFacetStatus:
      additionalProperties: false
      properties:
        min:
          anyOf:
          - type: number
          - type: integer
          - enum:
            - -inf
            - +inf
            - inf
            type: string
          - type: string
          description: Selected minimum value of the range facet.
          title: Min
        max:
          anyOf:
          - type: number
          - type: integer
          - enum:
            - -inf
            - +inf
            - inf
            type: string
          - type: string
          description: Selected maximum value of the range facet.
          title: Max
      title: RangeFacetStatus
      type: object
    VariationsMapAnd:
      additionalProperties: false
      properties:
        and_:
          items:
            type: array
          title: And
          type: array
      required:
      - and_
      title: VariationsMapAnd
      type: object
    VariationsMapOr:
      additionalProperties: false
      properties:
        or_:
          items:
            type: array
          title: Or
          type: array
      required:
      - or_
      title: VariationsMapOr
      type: object
    FilterMatchType:
      enum:
      - any
      - all
      - none
      title: FilterMatchType
      type: string
    SearchResponse:
      additionalProperties: false
      properties:
        result_sources:
          description: Summary of result sources.
          allOf:
          - $ref: '#/components/schemas/ResultSources'
          title: Result Sources
        facets:
          description: An array of facets associated with the items returned by the search query.
          items:
            discriminator:
              mapping:
                hierarchical: '#/components/schemas/HierarchicalFacet'
                multiple: '#/components/schemas/SingleOrMultipleFacet'
                range: '#/components/schemas/RangeFacet'
                single: '#/components/schemas/SingleOrMultipleFacet'
              propertyName: type
            oneOf:
            - $ref: '#/components/schemas/RangeFacet'
            - $ref: '#/components/schemas/SingleOrMultipleFacet'
            - $ref: '#/components/schemas/HierarchicalFacet'
          title: Facets
          type: array
        groups:
          description: An array of item groups and the number of results belonging to each group.
          items:
            $ref: '#/components/schemas/Group'
          title: Groups
          type: array
        results:
          items:
            $ref: '#/components/schemas/SearchandizedResult'
          title: Results
          type: array
        sort_options:
          description: Sort options configured for this index through the [Sort options API](https://docs.constructor.com/reference/v1-sort-options-create-or-replace-sort-options). It does not restrict the values accepted by `sort_by` or `sort_order`. Any sortable field can be used in ascending or descending order. Returns an empty array when no sort options are configured, in which case results default to sorting by relevance in descending order.
          items:
            $ref: '#/components/schemas/SortOption'
          title: Sort Options
          type: array
        refined_content:
          description: Arbitrary content attached to the search query via [content rule](#). Constructor doesn't enforce any restrictions on the attached data except for a size limit of 200kB, and just returns it as-is when there is a query match. There can be several rules attached to the same query, so the `refined_content` itself is an array of objects.
          items:
            additionalProperties:
              additionalProperties: true
              type: object
            type: object
          title: Refined Content
          type: array
        total_num_results:
          description: Total count of results within the section
          minimum: 0
          title: Total Num Results
          type: integer
        features:
          description: State of features for Affinity Engine, Searchandizing, Personalization and Learn To Rank
          items:
            $ref: '#/components/schemas/Feature'
          title: Features
          type: array
        related_searches:
          description: An array of related queries.
          items:
            $ref: '#/components/schemas/RelatedSearch'
          title: Related Searches
          type: array
        related_browse_pages:
          description: An array of related browse pages.
          items:
            $ref: '#/components/schemas/RelatedBrowseEntity'
          title: Related Browse Pages
          type: array
      required:
      - result_sources
      - facets
      - groups
      - results
      - sort_options
      - refined_content
      - total_num_results
      - features
      - related_searches
      - related_browse_pages
      title: Search response
      type: object
    RelatedSearch:
      additionalProperties: false
      properties:
        query:
          description: The related search query.
          title: Query
          type: string
      required:
      - query
      title: RelatedSearch
      type: object
    VariationsMapCountAggregation:
      properties:
        aggregation:
          title: Aggregation
          type: string
          enum:
          - count
      required:
      - aggregation
      title: VariationsMapCountAggregation
      type: object
    DictOrJsonStringWithDict:
      anyOf:
      - title: object
        type: object
      - format: json
        title: Encoded JSON string
        type: string
      title: DictOrJsonStringWithDict
    VariationsMapFilterBy:
      discriminator:
        mapping:
          and: '#/components/schemas/VariationsMapAnd'
          not: '#/components/schemas/VariationsMapNot'
          or: '#/components/schemas/VariationsMapOr'
          range: '#/components/schemas/VariationsMapRange'
          single: '#/components/schemas/VariationsMapSingleFilter'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/VariationsMapRange'
      - $ref: '#/components/schemas/VariationsMapSingleFilter'
      - $ref: '#/components/schemas/VariationsMapOr'
      - $ref: '#/components/schemas/VariationsMapAnd'
      - $ref: '#/components/schemas/VariationsMapNot'
      title: VariationsMapFilterBy
    VariationsReturnType:
      enum:
      - default
      - all
      - matched
      title: VariationsReturnType
      type: string
    RedirectResponse:
      additionalProperties: false
      properties:
        redirect:
          $ref: '#/components/schemas/Redirect'
      required:
      - redirect
      title: Redirect response
      type: object
    FacetOption:
      additionalProperties: false
      properties:
        display_name:
          description: The name of the facet option as it is displayed to end users. Note that in `filters` parameter you need to use not `display_name` but `name`.
          title: Display Name
          type: string
        status:
          description: '`selected` if this option is selected in the current search request, empty string otherwise.'
          enum:
          - selected
          - ''
          title: Status
          type: string
        value:
          description: 'The value that should be passed in `filters` to select this option: `filters[name]=value`'
          title: Value
          type: string
        count:
          description: Number of items in the current search that match this option.
          minimum: 0
          title: Count
          type: integer
        data:
          description: Object containing custom data associated with this facet option. An empty object (`{}`) if no data is currently associated with this option.
          title: Data
          type: object
        range:
          description: 'Array containing 2 values: the parsed `min` & `max` values that are represented by this facet option. The field exists only for options of a facet with type `range` or `single` if it is configured specially.'
          title: Range
          items:
            anyOf:
            - type: number
            - type: integer
            - enum:
              - -inf
              - +inf
              - inf
              type: string
          type: array
      required:
      - display_name
      - status
      - value
      - count
      title: FacetOption
      type: object
    FmtOptions:
      additionalProperties: false
      properties:
        fields:
          description: A list of specific item fields to return in the response. Allows the request to control which fields are returned.
          title: Fields
          items:
            maxLength: 300
            minLength: 1
            type: string
            examples:
            - image_url
            - price
            - brand
          maxItems: 20
          type: array
        show_hidden_fields:
          default: false
          description: A flag to return all `hidden` fields in the response.
          examples:
          - false
          - true
          title: Show Hidden Fields
          type: boolean
        hidden_fields:
          description: A list of specific hidden fields to return in the response. Unlike `show_hidden_fields` this parameter allows the request to control which `hidden` fields are returned.  Used to return item fields for a particular store or user segment.
          title: Hidden Fields
          items:
            maxLength: 300
            minLeng

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/constructorio/refs/heads/main/openapi/constructorio-search-results-api-openapi.yml