Constructor.io Variations API

openapi: 3.2.0
info:
  contact:
    email: support@constructor.io
  title: Catalog management Variations API
  version: '0.1'
servers:
- url: https://ac.cnstrc.com
security: []
tags:
- name: Variations
paths:
  /v2/variations:
    get:
      tags:
      - Variations
      operationId: v2-variations-retrieve-variations
      summary: Retrieve variations
      description: '**🔐 This endpoint requires HTTP authentication (either Basic or Bearer).**

        For authenticating with Bearer token, required scopes are: `catalog(r)`.


        Retrieve all item variations, optionally filtered by id(s).'
      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: 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: id
        in: query
        schema:
          title: Id
          description: The ID(s) of the variations to return.
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 250
            examples:
            - red-nike-shoes
            - variation-123
          maxItems: 1000
        required: false
      - name: item_id
        in: query
        schema:
          title: Item Id
          description: The item ID(s) of variations to return.
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 250
            examples:
            - nike-shoes
            - product-123
          maxItems: 1000
        required: false
      - name: next_page_cursor
        in: query
        schema:
          title: Pagination cursor
          description: Pagination cursor from which to start returning results. Cannot be used together with `page` or `offset`.
          maxLength: 250
          minLength: 1
          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: 100
          minimum: 1
          maximum: 1000
          examples:
          - 100
          - 500
          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: 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/VariationListGetResponse'
        '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:
        - catalog(r)
    put:
      tags:
      - Variations
      operationId: v2-variations-create-or-replace-variations
      summary: Create or replace variations
      description: '**🔐 This endpoint requires HTTP authentication (either Basic or Bearer).**

        For authenticating with Bearer token, required scopes are: `catalog(w)`, `search_suggestions(w)`.


        Create item variations or replace the data of existing item variations. Returns an identifier for a background task.'
      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: 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
      - name: force
        in: query
        schema:
          title: Force
          description: A flag to process the catalog even if it will invalidate a large part of existing data. Defaults to `False`.
          examples:
          - false
          - true
          type: boolean
        required: false
      - name: notification_email
        in: query
        schema:
          title: Notification Email
          description: The email address(es) to send a notification to if the task fails. Multiple addresses may be specified for multiple recipients.
          type: array
          items:
            type: string
            format: email
            examples:
            - user@example.com
        required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariationListPutRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationListPutResponse'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationListPutAcceptedResponse'
        '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.
        '409':
          description: Conflict
        '429':
          description: Rate limit breached
      security:
      - http_basic_auth: []
      - http_bearer_auth:
        - catalog(w)
        - search_suggestions(w)
    patch:
      tags:
      - Variations
      operationId: v2-variations-update-variations
      summary: Update variations
      description: '**🔐 This endpoint requires HTTP authentication (either Basic or Bearer).**

        For authenticating with Bearer token, required scopes are: `catalog(w)`, `search_suggestions(w)`.


        Update existing item variation data. Data included in the request will be merged with data of the existing item variations. Returns an identifier for a background task.'
      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: 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
      - name: force
        in: query
        schema:
          title: Force
          description: A flag to process the catalog even if it will invalidate a large part of existing data. Defaults to `False`.
          examples:
          - false
          - true
          type: boolean
        required: false
      - name: notification_email
        in: query
        schema:
          title: Notification Email
          description: The email address(es) to send a notification to if the task fails. Multiple addresses may be specified for multiple recipients.
          type: array
          items:
            type: string
            format: email
            examples:
            - user@example.com
        required: false
      - name: on_missing
        in: query
        schema:
          description: The strategy for handling variations which are exist in the request and do not exist in the system. `IGNORE` silently prevents adding them to the system, `CREATE` creates them, `FAIL` fails the ingestion in case of their presence.
          default: FAIL
          examples:
          - FAIL
          - IGNORE
          - CREATE
          allOf:
          - $ref: '#/components/schemas/MissingRecordsStrategy'
        required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariationListPatchRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationListPatchResponse'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationListPatchAcceptedResponse'
        '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.
        '409':
          description: Conflict
        '429':
          description: Rate limit breached
      security:
      - http_basic_auth: []
      - http_bearer_auth:
        - catalog(w)
        - search_suggestions(w)
    delete:
      tags:
      - Variations
      operationId: v2-variations-delete-variations
      summary: Delete variations
      description: '**🔐 This endpoint requires HTTP authentication (either Basic or Bearer).**

        For authenticating with Bearer token, required scopes are: `catalog(w)`, `search_suggestions(w)`.


        Delete item variations. Returns an identifier for a background task.'
      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: 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
      - name: force
        in: query
        schema:
          title: Force
          description: A flag to process the catalog even if it will invalidate a large part of existing data. Defaults to `False`.
          examples:
          - false
          - true
          type: boolean
        required: false
      - name: notification_email
        in: query
        schema:
          title: Notification Email
          description: The email address(es) to send a notification to if the task fails. Multiple addresses may be specified for multiple recipients.
          type: array
          items:
            type: string
            format: email
            examples:
            - user@example.com
        required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariationListDeleteRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationListDeleteResponse'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationListDeleteAcceptedResponse'
        '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.
        '409':
          description: Conflict
        '429':
          description: Rate limit breached
      security:
      - http_basic_auth: []
      - http_bearer_auth:
        - catalog(w)
        - search_suggestions(w)
  /v2/variations/{variation_id}:
    get:
      tags:
      - Variations
      operationId: v2-variations-retrieve-variation
      summary: Retrieve variation
      description: '**🔐 This endpoint requires HTTP authentication (either Basic or Bearer).**

        For authenticating with Bearer token, required scopes are: `catalog(r)`.


        Retrieve an item variation.'
      parameters:
      - name: variation_id
        in: path
        required: true
        schema:
          type: string
          examples:
          - red-nike-shoes
          - variation-123
      - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariationGetResponse'
        '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:
        - catalog(r)
components:
  schemas:
    VariationListPatchAcceptedResponse:
      title: VariationListPatchAcceptedResponse
      type: object
      properties:
        message:
          title: Message
          description: Info message
          type: string
      required:
      - message
    VariationListPatchResponse:
      title: VariationListPatchResponse
      type: object
      properties:
        task_id:
          title: Task Id
          type: integer
        task_status_path:
          title: Task Status Path
          type: string
      required:
      - task_id
      - task_status_path
    VariationListPutAcceptedResponse:
      title: VariationListPutAcceptedResponse
      type: object
      properties:
        message:
          title: Message
          description: Info message
          type: string
      required:
      - message
    VariationListDeleteRequestBody:
      title: VariationListDeleteRequestBody
      type: object
      properties:
        variations:
          title: Variations
          description: Array of variation IDs you want to delete.
          minItems: 1
          maxItems: 10000
          type: array
          items:
            $ref: '#/components/schemas/VariationBase'
      required:
      - variations
    VariationListDeleteAcceptedResponse:
      title: VariationListDeleteAcceptedResponse
      type: object
      properties:
        message:
          title: Message
          description: Info message
          type: string
      required:
      - message
    VariationListDeleteResponse:
      title: VariationListDeleteResponse
      type: object
      properties:
        task_id:
          title: Task Id
          type: integer
        task_status_path:
          title: Task Status Path
          type: string
      required:
      - task_id
      - task_status_path
    FacetValuesCoercedToList:
      title: FacetValuesCoercedToList
      type: array
      items:
        $ref: '#/components/schemas/FacetValue'
    VariationListGetResponse:
      title: VariationListGetResponse
      type: object
      properties:
        total_count:
          title: Total Count
          description: Total number of variations. Omitted when using cursor-based pagination (`next_page_cursor`).
          minimum: 0
          examples:
          - 100
          - 5000
          type: integer
        variations:
          title: Variations
          type: array
          items:
            $ref: '#/components/schemas/VariationGetResponse'
        next_page_cursor:
          title: Pagination cursor
          description: Pagination cursor to use to receive the next page of results. The value is returned by the previous page response. Cannot be used together with `page` or `offset`.
          maxLength: 250
          minLength: 1
          examples:
          - red-nike-shoes
          - variation-123
          type: string
      required:
      - variations
    VariationGetResponse:
      title: VariationGetResponse
      type: object
      properties:
        id:
          title: ID
          description: The ID of the variation, must be unique.
          minLength: 1
          maxLength: 250
          type: string
        item_id:
          title: Item ID
          description: The ID of the item this variation is attached to.
          minLength: 1
          maxLength: 250
          type: string
        name:
          title: Name
          description: The name of the variation, as it will appear in the results. Contains at least one alphanumeric character.
          maxLength: 250
          minLength: 1
          type: string
        suggested_score:
          title: Score
          description: A number that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
          minimum: -1
          maximum: 500000000
          type: integer
        data:
          title: Data
          description: Object containing additional data attached to this variation.
          allOf:
          - $ref: '#/components/schemas/VariationMetadataResponse'
        updated_at:
          title: Updated at
          description: A date when the variation was updated.
          type: string
          format: date-time
      required:
      - id
      - item_id
      - updated_at
      additionalProperties: false
    VariationMetadata:
      title: VariationMetadata
      description: 'Additional data about item. In addition to the listed properties

        you can also provide any other information you want to associate

        with that item. No special validation is made for that data.'
      type: object
      properties:
        keywords:
          title: Keywords
          description: An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself.
          type: array
          items:
            type: string
            examples:
            - running
            - athletic
            - sports
        url:
          title: Url
          description: A URL to directly send the user after selecting the item. Might be required in some cases. Please contact support@constructor.io if you have questions around that.
          examples:
          - http://www.example.com/product/123
          - /products/shoes
          type: string
        image_url:
          title: Image Url
          description: A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied).
          examples:
          - http://www.example.com/images/product.jpg
          type: string
        facets:
          title: Facets
          description: 'Warning: ingesting data directly as facets has been deprecated. Please ingest the data as metadata instead, and create a facet configuration as shown in our guide on global facet configuration. '
          deprecated: true
          examples:
          - color:
            - red
            - blue
            size:
            - L
            - XL
          allOf:
          - $ref: '#/components/schemas/Facets'
        group_ids:
          title: Group Ids
          description: You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io group_ids can be used as filters in search, autosuggest, and browse requests.
          type: array
          items:
            type: string
            examples:
            - shoes
            - athletic
        description:
          title: Description
          description: A description for this item. The maximum length of this field is 4000 characters.
          examples:
          - A comfortable running shoe with cushioned sole
          maxLength: 4000
          type: string
        active:
          title: Active
          examples:
          - true
          - false
          type: boolean
        is_default:
          title: Is Default
          description: Whether this variation should always be returned as the best matching variation.
          examples:
          - true
          - false
          type: boolean
        __cnstrc_release_time:
          title: Release time
          description: Date and time of item's release, useful to hide items from search results until its official release.
          examples:
          - '2024-01-15T10:30:00Z'
          type: string
          format: date-time
    Variation:
      title: Variation
      type: object
      properties:
        id:
          title: Id
          description: The ID of the variation, must be unique.
          examples:
          - red-nike-shoes
          - variation-123
          minLength: 1
          maxLength: 250
          type: string
        item_id:
          title: Item Id
          description: The ID of the item this variation is attached to.
          examples:
          - nike-shoes
          - product-123
          minLength: 1
          maxLength: 250
          type: string
        name:
          title: Name
          description: The name of the variation, as it will appear in the results. Must contain at least one alphanumeric character.
          maxLength: 250
          minLength: 1
          examples:
          - Running Shoes - Size 10
          - Blue T-Shirt - Large
          type: string
        suggested_score:
          title: Suggested Score
          description: A number that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
          minimum: -1
          maximum: 500000000
          examples:
          - 100
          - 9999
          type: integer
        data:
          title: Data
          description: Object containing additional data, that should be attached to this variation. The maximum size of data object is limited to 200kb. The average size of data objects for all ingested items and variations should not exceed 30kb.
          examples:
          - url: http://example.com/variation
            size: L
          allOf:
          - $ref: '#/components/schemas/VariationMetadata'
      required:
      - id
      - item_id
      additionalProperties: false
    Facets:
      title: Facets
      type: object
      additionalProperties:
        $ref: '#/components/schemas/FacetValuesCoercedToList'
    VariationPatch:
      title: VariationPatch
      type: object
      properties:
        id:
          title: Id
          description: The ID of the variation, must be unique.
          examples:
          - red-nike-shoes
          - variation-123
          minLength: 1
          maxLength: 250
          type: string
        item_id:
          title: Item Id
          description: The ID of the item this variation is attached to.
          examples:
          - nike-shoes
          - product-123
          minLength: 1
          maxLength: 250
          type: string
        name:
          title: Name
          description: The name of the variation, as it will appear in the results. Must contain at least one alphanumeric character.
          maxLength: 250
          minLength: 1
          examples:
          - Running Shoes - Size 10
          - Blue T-Shirt - Large
          type: string
        suggested_score:
          title: Suggested Score
          description: A number that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
          minimum: -1
          maximum: 500000000
          examples:
          - 100
          - 9999
          type: integer
        data:
          title: Data
          description: Object containing additional data, that should be attached to this variation. The maximum size of data object is limited to 200kb. The average size of data objects for all ingested items and variations should not exceed 30kb.
          examples:
          - url: http://example.com/variation
            size: L
          allOf:
          - $ref: '#/components/schemas/VariationMetadata'
      required:
      - id
      additionalProperties: false
    FacetValue:
      title: FacetValue
      anyOf:
      - type: string
        minLength: 0
        maxLength: 200
      - type: integer
      - type: number
    VariationListPatchRequestBody:
      title: VariationListPatchRequestBody
      type: object
      properties:
        variations:
          title: Variations
          description: Array of variations you want to update.
          minItems: 1
          maxItems: 10000
          type: array
          items:
            $ref: '#/components/schemas/VariationPatch'
      required:
      - variations
    VariationListPutRequestBody:
      title: VariationListPutRequestBody
      type: object
      properties:
        variations:
          title: Variations
          description: Array of variations you want to create or replace.
          minItems: 1
          maxItems: 10000
          type: array
          items:
            $ref: '#/components/schemas/Variation'
      required:
      - variations
    VariationBase:
      title: VariationBase
      type: object
      properties:
        id:
          title: Id
          description: The ID of the variation, must be unique.
          examples:
          - red-nike-shoes
          - variation-123
          minLength: 1
          maxLength: 250
          type: string
      required:
      - id
      additionalProperties: false
    VariationListPutResponse:
      title: VariationListPutResponse
      type: object
      properties:
        task_id:
          title: Task Id
          type: integer
        task_status_path:
          title: Task Status Path
          type: string
      required:
      - task_id
      - task_status_path
    MissingRecordsStrategy:
      title: MissingRecordsStrategy
      enum:
      - CREATE
      - IGNORE
      - FAIL
    VariationMetadataResponse:
      title: VariationMetadataResponse
      description: 'Additional data about item. In addition to the listed properties

        you can also provide any other information you want to associate

        with that item. No special validation is made for that data.'
      type: object
      properties:
        keywords:
          title: Keywords
          description: An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself.
          type: array
          items:
            type: string
            examples:
            - running
            - athletic
            - sports
        url:
          title: Url
          description: A URL to directly send the user after selecting the item. Might be required in some cases. Please contact support@constructor.io if you have questions around that.
          examples:
          - http://www.example.com/product/123
          - /products/shoes
          type: string
        image_url:
          title: Image Url
          description: A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied).
          examples:
          - http://www.example.com/images/product.jpg
          type: string
        facets:
          title: Facets
          description: 'Warning: ingesting data directly as facets has been deprecated. Please ingest the data as metadata instead, and create a facet configuration as shown in our guide on global facet configuration. '
          deprecated: true
          examples:
          - color:
            - red
            - blue
            size:
            - L
            - XL
          allOf:
          - $ref: '#/components/schemas/Facets'
        group_ids:
          title: Group Ids
          description: You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io group_ids can be used as filters in search, autosuggest, and browse requests.
          type: array
          items:
            type: string
            examples:
            - shoes
            - athletic
        description:
          title: Description
          description: A description for this item. The maximum length of this field is 4000 characters.
          examples:
          - A comfortable running shoe with cushioned sole
          maxLength: 4000
          type: string
        active:
          title: Active
          examples:
          - true
          - false
          type: boolean
        is_default:
          title: Is Default
          description: Whether this variation should always be returned as the best matching variation.
          examples:
          - true
          - false
          type: boolean
      additionalProperties: true
  securitySchemes:
    http_basic_auth:
      type: http
      scheme: basic
    http_bearer_auth:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: false