openapi: 3.1.0
info:
  contact:
    email: support@constructor.io
  title: Recommendations
  version: '0.1'
servers:
- url: https://ac.cnstrc.com
security: []
tags:
- name: Search results
- name: Natural language search results
- name: Autocomplete results
- name: Browse results
- name: Browse groups
- name: Browse facets
- name: Browse collections
- name: Recommendation results
paths:
  /recommendations/v1/pods/{pod_id}:
    get:
      tags:
      - Recommendation results
      operationId: v1-recommendations-get-pod-results
      summary: Retrieve by pod
      description: Retrieve AI optimized recommendation results for products (or optionally other sections) by pod identifier. To learn more about pods, go [here](/docs/products-recommendations-learn-about-recommendations#pods).
      parameters:
      - name: pod_id
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: query
        schema:
          description: The key of the index to use.
          examples:
          - key_K2pX7vBnU0bgA5xp
          title: Key
          maxLength: 100
          minLength: 1
          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: item_id
        in: query
        schema:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          description: 'The ID of the item to recommend additional items for. This parameter is required for the following recommendation strategies

            * `alternative_items`

            * `complementary_items`

            * `bundles`

            * `custom_item_item`'
          title: Item Id
        required: false
      - name: variation_id
        in: query
        schema:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          description: The ID of the item variation to recommend additional items for. This parameter can be used with exactly one item_id specified in the request and is not required.
          title: Variation ID
        required: false
      - name: term
        in: query
        schema:
          description: 'The term to recommend items for. This parameter is required for the following recommendation strategies

            * `query_recommendations`'
          title: Term
          maxLength: 100
          minLength: 0
          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.


            This parameter is required for the following recommendation strategies

            * `filtered_items`'
          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 Object containing any number of filters (inaccessible to end users) used to narrow the result set. Applied before filters accessible to end users. Only results that match the filters are returned.
          allOf:
          - $ref: '#/components/schemas/DictOrJsonStringWithDict'
          title: Pre Filter Expression
        required: false
      - name: num_results
        in: query
        schema:
          default: 10
          description: The maximum number of recommended items to retrieve
          maximum: 100
          minimum: 0
          title: Num Results
          type: integer
        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)
          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 the results returned
          allOf:
          - $ref: '#/components/schemas/FmtOptions'
          title: Fmt Options
        required: false
        style: deepObject
        explode: true
      - name: origin_referrer
        in: query
        schema:
          description: The url or app location where the request originated.
          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`.
          title: C
          maxLength: 100
          minLength: 1
          type: string
        required: false
      - name: us
        in: query
        schema:
          description: User segment is a client context value (such as platform, location, etc.) that is used to evaluate redirect or refined tag rules. You can supply multiple segments by passing multiple `us` arguments.
          title: us
          items:
            minLength: 1
            type: string
          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.


            At least one of the parameters `i` or `ui` is required for the following recommendation strategies

            * `recently_viewed_items`

            * `user_featured_items`

            * `abandoned_in_cart`

            * `custom_user_item`'
          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.
          title: S
          type: integer
        required: false
      - name: sl
        in: query
        schema:
          description: SL data
          title: Sl
          additionalProperties:
            type: string
          type: object
        required: false
      - name: i
        in: query
        schema:
          description: 'A globally unique identifier for the user browser (or mobile application instance) making the request.


            At least one of the parameters `i` or `ui` is required for the following recommendation strategies

            * `recently_viewed_items`

            * `user_featured_items`

            * `abandoned_in_cart`'
          title: I
          type: string
        required: false
      - name: q
        in: query
        schema:
          deprecated: true
          description: '**DEPRECATED. Please, use `term` instead**'
          title: Q
          maxLength: 100
          minLength: 0
          type: string
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationsPodsGetResponse'
        '400':
          description: Validation Error
        '404':
          description: Not Found
      security: []
components:
  schemas:
    DictOrJsonStringWithDict:
      anyOf:
      - title: object
        type: object
      - format: json
        title: Encoded JSON string
        type: string
      title: DictOrJsonStringWithDict
    FacetOptionSortOrder:
      enum:
      - relevance
      - value
      - num_matches
      title: FacetOptionSortOrder
      type: string
    FilterMatchType:
      enum:
      - any
      - all
      - none
      title: FilterMatchType
      type: string
    Filters:
      propertyNames:
        minLength: 1
      title: Filters
      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
            minLength: 1
            type: string
            examples:
            - inventory_count
            - store_availability
          maxItems: 30
          type: array
        variations_return_type:
          description: A flag to return `default`, `all`, or `matched` variations.
          examples:
          - default
          allOf:
          - $ref: '#/components/schemas/VariationsReturnType'
        groups_max_depth:
          default: 1
          description: The maximum depth of the group hierarchy in the response.
          examples:
          - 1
          - 3
          title: Groups Max Depth
          type: integer
        groups_start:
          default: current
          description: A flag to specify the start of the group hierarchy returned in the response. `current` returns groups starting from the currently selected one. `top` returns groups starting from the root category in the hierarchy. `group_id:{id}`, returns the whole tree starting from group with the provided ID.
          examples:
          - current
          - top
          - group_id:jeans
          title: Groups Start
          type: string
        groups_sort_by:
          description: A string indicating the option to sort results by. Sorting options are created from item fields and facets in the product catalog.
          examples:
          - relevance
          allOf:
          - $ref: '#/components/schemas/FacetOptionSortOrder'
        groups_sort_order:
          description: A flag to sort either `ascending` or `descending`.
          examples:
          - descending
          allOf:
          - $ref: '#/components/schemas/SortOrderType'
        show_hidden_facets:
          default: false
          description: A flag to return all facets configured as `hidden` in `response.facets`.
          examples:
          - false
          - true
          title: Show Hidden Facets
          type: boolean
        hidden_facets:
          description: A list of specific hidden facets to return in the response. Unlike `show_hidden_facets` this parameter allows the request to control which hidden facets are returned.  Used to return facets for a particular store or user segment.
          title: Hidden Facets
          items:
            maxLength: 100
            minLength: 1
            type: string
            examples:
            - store_id
            - region
          maxItems: 50
          type: array
        show_hidden_facet_options:
          description: A flag to return all `hidden` facets options in the response.
          examples:
          - true
          - false
          title: Show Hidden Facet Options
          type: boolean
        show_protected_facets:
          default: false
          description: A flag to return all `protected` facets in the response. Requires authentication.
          examples:
          - false
          - true
          title: Show Protected Facets
          type: boolean
        facet_options:
          description: A list of specific facet options per facet to return in the response. This parameter accepts up to 5 facets and works only with facets of type `multiple`. Invalid facet options will be ignored. Used to return facet options for a particular facet like store or user segment.
          examples:
          - brand:
            - nike
            - adidas
            color:
            - red
            - blue
          title: Facet Options
          additionalProperties:
            items:
              maxLength: 100
              minLength: 1
              type: string
            maxItems: 15
            type: array
          type: object
        facet_groups_limit:
          description: The maximum limit of the facet groups returned in the response.
          examples:
          - 10
          title: Facet Groups Limit
          minimum: 0
          type: integer
        show_hidden_sort_options:
          description: A flag to return all sort options configured as `hidden` in `response.sort_options`.
          examples:
          - true
          - false
          title: Show Hidden Sort Options
          type: boolean
        hidden_sort_options:
          description: A list of `sort_by` fields whose hidden sort options should be included in the response. Unlike `show_hidden_sort_options` this parameter allows you to specify exactly which hidden sort options are returned.
          title: Hidden Sort Options
          items:
            maxLength: 100
            minLength: 1
            type: string
            examples:
            - price
            - rating
          maxItems: 25
          type: array
      title: FmtOptions
      type: object
    SortOrderType:
      enum:
      - ascending
      - descending
      title: SortOrderType
      type: string
    VariationsMap:
      properties:
        filter_by:
          description: A filtering expression that should be used to filter variations before doing any aggregations
          allOf:
          - $ref: '#/components/schemas/VariationsMapFilterBy'
          title: Filter By
        group_by:
          description: An array of fields that should be used to group variations. Variations which share the value of all fields specified here will all fall under one group
          title: Group By
          items:
            $ref: '#/components/schemas/VariationsMapGrouping'
          maxItems: 5
          type: array
        values:
          description: A set of aggregations that should be applied to each variation group. The object keys specify the name of the field under which each aggregated value will be returned in the response
          title: Values
          type: object
          additionalProperties:
            discriminator:
              mapping:
                all: '#/components/schemas/VariationsMapSimpleAggregation'
                count: '#/components/schemas/VariationsMapCountAggregation'
                distinct: '#/components/schemas/VariationsMapSimpleAggregation'
                field_count: '#/components/schemas/VariationsMapSimpleAggregation'
                first: '#/components/schemas/VariationsMapSimpleAggregation'
                max: '#/components/schemas/VariationsMapSimpleAggregation'
                min: '#/components/schemas/VariationsMapSimpleAggregation'
                value_count: '#/components/schemas/VariationsMapValueCountAggregation'
              propertyName: aggregation
            oneOf:
            - $ref: '#/components/schemas/VariationsMapSimpleAggregation'
            - $ref: '#/components/schemas/VariationsMapCountAggregation'
            - $ref: '#/components/schemas/VariationsMapValueCountAggregation'
        dtype:
          description: The expected data type of the variations_map objects in the response
          enum:
          - array
          - object
          title: Dtype
          type: string
      required:
      - values
      - dtype
      title: VariationsMap
      type: object
    VariationsMapAnd:
      additionalProperties: false
      properties:
        and_:
          items:
            type: array
          title: And
          type: array
      required:
      - and_
      title: VariationsMapAnd
      type: object
    VariationsMapCountAggregation:
      properties:
        aggregation:
          title: Aggregation
          type: string
          enum:
          - count
      required:
      - aggregation
      title: VariationsMapCountAggregation
      type: object
    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
    VariationsMapGrouping:
      properties:
        name:
          pattern: ^\w+([ ]?[\w]+)*$
          title: Name
          type: string
        field:
          minLength: 1
          title: Field
          type: string
      required:
      - name
      - field
      title: VariationsMapGrouping
      type: object
    VariationsMapNot:
      additionalProperties: false
      properties:
        not_:
          type: object
          title: Not
      required:
      - not_
      title: VariationsMapNot
      type: object
    VariationsMapOr:
      additionalProperties: false
      properties:
        or_:
          items:
            type: array
          title: Or
          type: array
      required:
      - or_
      title: VariationsMapOr
      type: object
    VariationsMapRange:
      additionalProperties: false
      properties:
        field:
          description: Path to a metadata field (dot-separated)
          minLength: 1
          title: Field
          type: string
        range:
          description: This filter matches items where the specified field is within the specified range (min and max). The values are inclusive. Use "inf" for an unbounded upper limit or "-inf" for an unbounded lower limit.
          items:
            anyOf:
            - enum:
              - inf
              - -inf
              type: string
            - type: integer
            - type: number
          maxItems: 2
          minItems: 2
          title: Range
          type: array
      required:
      - field
      - range
      title: VariationsMapRange
      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
    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
    VariationsMapValueCountAggregation:
      properties:
        aggregation:
          title: Aggregation
          type: string
          enum:
          - value_count
        field:
          minLength: 1
          title: Field
          type: string
        value:
          anyOf:
          - type: boolean
          - type: integer
          - type: number
          - type: string
          title: Value
      required:
      - aggregation
      - field
      - value
      title: VariationsMapValueCountAggregation
      type: object
    VariationsReturnType:
      enum:
      - default
      - all
      - matched
      title: VariationsReturnType
      type: string
    RecommendationsPodsGetResponse:
      additionalProperties: false
      properties:
        request:
          description: The request arguments how they were interpreted by the API. This field is of arbitrary type, ie it doesn't have a guaranteed schema, and data from it shouldn't be used programmatically, it is for debugging purposes only.
          title: Request
          type: object
        result_id:
          title: Result Id
          type: string
        response:
          $ref: '#/components/schemas/PodEndpointResponseField'
      required:
      - request
      - response
      title: RecommendationsPodsGetResponse
      type: object
    DataField:
      properties:
        id:
          title: Id
          type: string
        variation_id:
          title: Variation Id
          type: string
      required:
      - id
      title: DataField
      type: object
    PodEndpointResponseField:
      properties:
        results:
          items:
            $ref: '#/components/schemas/ResultField'
          title: Results
          type: array
        total_num_results:
          title: Total Num Results
          type: integer
        pod:
          $ref: '#/components/schemas/PodField'
      required:
      - results
      - total_num_results
      - pod
      title: PodEndpointResponseField
      type: object
    PodField:
      properties:
        id:
          title: Id
          type: string
        display_name:
          title: Display Name
          type: string
        channels:
          title: Channels
          items:
            type: string
          type: array
      required:
      - id
      - display_name
      title: PodField
      type: object
    ResultField:
      properties:
        data:
          $ref: '#/components/schemas/DataField'
        value:
          title: Value
          type: string
        is_slotted:
          title: Is Slotted
          type: boolean
        labels:
          default: {}
          title: Labels
          type: object
        strategy:
          $ref: '#/components/schemas/StrategyField'
      required:
      - data
      - value
      - is_slotted
      title: ResultField
      type: object
    StrategyField:
      properties:
        id:
          title: Id
          type: string
        type:
          title: Type
          type: string
      required:
      - id
      title: StrategyField
      type: object
  securitySchemes:
    http_basic_auth:
      type: http
      scheme: basic
    http_bearer_auth:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: false