Constructor Browse API

openapi: 3.1.0
info:
  contact:
    email: support@constructor.io
  title: Browse
  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
paths:
  /browse/{filter_name}/{filter_value}:
    get:
      tags:
      - Browse results
      operationId: v1-browse-get-browse-results
      summary: Retrieve by filter name/value
      description: Retrieve AI optimized browse results for products (or optionally other sections) by facet name and value.
      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
          format: path
          examples:
          - Nike
          - Red
          - 10-20
      - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowseGetResponse'
        '400':
          description: Validation Error
      security: []
  /browse/collection_id/{collection_id_value}:
    get:
      tags:
      - Browse results
      operationId: v1-browse-get-browse-results-by-collection-id
      summary: Retrieve by collection ID
      description: Retrieve AI optimized browse results for products (or optionally other sections) by collection ID.
      parameters:
      - name: collection_id_value
        in: path
        required: true
        schema:
          type: string
          format: path
          examples:
          - summer-sale
          - gifts
      - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowseGetResponse'
        '400':
          description: Validation Error
        '404':
          description: Not Found
      security: []
  /browse/group_id/{group_id_value}:
    get:
      tags:
      - Browse results
      operationId: v1-browse-get-browse-results-by-group-id
      summary: Retrieve by group ID
      description: Retrieve AI optimized browse results for products (or optionally other sections) by item group ID.
      parameters:
      - name: group_id_value
        in: path
        required: true
        schema:
          type: string
          format: path
          examples:
          - jeans
          - snowboards
      - 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/BrowseFmtOptions'
          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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowseGetResponse'
        '400':
          description: Validation Error
      security: []
  /browse/items:
    get:
      tags:
      - Browse results
      operationId: v1-browse-get-browse-items-results
      summary: Retrieve by item ID
      description: Retrieve browse results for products (or optionally other sections) by item ID(s).
      parameters:
      - 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: ids
        in: query
        schema:
          description: The ID(s) of the items to return.
          title: Ids
          items:
            minLength: 1
            type: string
            examples:
            - nike-shoes
            - product-123
          maxItems: 100
          type: array
        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: 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

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