Depict.AI Collections API

openapi: 3.1.0
info:
  title: Depict Lite Ab Test Collections API
  version: 1.0.0
  description: 'REST API behind Depict Lite, the native Shopify app: onboarding, collections, boost & bury, dashboards, A/B testing and multi-store management. Endpoints are served under the /api/lite prefix and require an Auth0-issued bearer token.'
servers:
- url: /api/lite
tags:
- name: Collections
paths:
  /collections:
    get:
      summary: List Collections
      operationId: list_collections_collections_get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiteCollectionListDto'
                title: Response List Collections Collections Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/award-status:
    get:
      summary: Get Award Status
      description: Get the award status configuration for the merchant.
      operationId: get_award_status_collections_award_status_get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardStatusConfig'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
    put:
      summary: Update Award Status
      description: Update the award status configuration for the merchant.
      operationId: update_award_status_collections_award_status_put
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardStatusConfig'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/nbr-of-active-collections:
    get:
      summary: Get Nbr Of Active Collections
      operationId: get_nbr_of_active_collections_collections_nbr_of_active_collections_get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - type: integer
                - type: 'null'
                title: Response Get Nbr Of Active Collections Collections Nbr Of Active Collections Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/data-sorted-by:
    post:
      summary: Get Data Sorted Collections
      operationId: get_data_sorted_collections_collections_data_sorted_by_post
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetDataSortedPaginatedCollectionsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaginatedDataCollectionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/activation:
    put:
      summary: Set Activation Status
      operationId: set_activation_status_collections_activation_put
      security:
      - Auth0: []
      parameters:
      - name: active
        in: query
        required: true
        schema:
          type: boolean
          title: Active
      - name: collection_id
        in: query
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}:
    get:
      summary: Get Collection
      operationId: get_collection_collections__collection_id__get
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Version
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiteCollectionDto'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
    put:
      summary: Update Collection
      operationId: update_collection_collections__collection_id__put
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiteCollectionUpdateInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                format: uuid
                title: Response Update Collection Collections  Collection Id  Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/products:
    post:
      summary: Get Collection Products
      description: 'Returns all products in a collection, sorted according to the given sort order,

        the collections pinned products, and either the collection''s boost bury rules or the specified rules.'
      operationId: get_collection_products_collections__collection_id__products_post
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: sort_order
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/LiteCollectionSortOrder'
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Version
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/BadgeBoostBuryRule'
                  - $ref: '#/components/schemas/CollectionBoostBuryRule'
                  - $ref: '#/components/schemas/TagBoostBuryRule'
                  discriminator:
                    propertyName: type
                    mapping:
                      badge: '#/components/schemas/BadgeBoostBuryRule'
                      collection: '#/components/schemas/CollectionBoostBuryRule'
                      tag: '#/components/schemas/TagBoostBuryRule'
              - type: 'null'
              title: Boost Bury Rules
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiteCollectionProductDto'
                title: Response Get Collection Products Collections  Collection Id  Products Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/shopify/shopify-ordering:
    post:
      summary: Get Db Shopify Ordering
      description: Returns all products in a collection, sorted according to exactly what is currently pushed to Shopify.
      operationId: get_db_shopify_ordering_collections__collection_id__shopify_shopify_ordering_post
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiteCollectionProductDto'
                title: Response Get Db Shopify Ordering Collections  Collection Id  Shopify Shopify Ordering Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/initial-products:
    get:
      summary: Get Initial Collection Products
      description: 'Returns all products in a collection, sorted according to what should be initially displayed in the Collection view.

        IE if the collection is completely untouched, without a Depict version, the current Shopify order.

        Or if there is at least one Depict version, sorted according to the currently saved main version, without any changes.'
      operationId: get_initial_collection_products_collections__collection_id__initial_products_get
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiteCollectionProductDto'
                title: Response Get Initial Collection Products Collections  Collection Id  Initial Products Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/product-clicks:
    get:
      summary: Get Collection Product Clicks
      operationId: get_collection_product_clicks_collections__collection_id__product_clicks_get
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: from_date
        in: query
        required: true
        schema:
          type: string
          format: date
          title: From Date
      - name: to_date
        in: query
        required: true
        schema:
          type: string
          format: date
          title: To Date
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCollectionProductClicksResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/product-orders:
    get:
      summary: Get Collection Product Orders
      operationId: get_collection_product_orders_collections__collection_id__product_orders_get
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: from_date
        in: query
        required: true
        schema:
          type: string
          format: date
          title: From Date
      - name: to_date
        in: query
        required: true
        schema:
          type: string
          format: date
          title: To Date
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                title: Response Get Collection Product Orders Collections  Collection Id  Product Orders Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/revert:
    post:
      summary: Revert Collection
      operationId: revert_collection_collections__collection_id__revert_post
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevertCollectionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/preview-url:
    post:
      summary: Get Collection Preview Url
      operationId: get_collection_preview_url_collections__collection_id__preview_url_post
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Version
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCollectionPreviewUrlRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GetCollectionPreviewUrlSuccessResponse'
                - $ref: '#/components/schemas/GetCollectionPreviewUrlWrongPasswordErrorResponse'
                discriminator:
                  propertyName: status
                  mapping:
                    success: '#/components/schemas/GetCollectionPreviewUrlSuccessResponse'
                    wrong_password: '#/components/schemas/GetCollectionPreviewUrlWrongPasswordErrorResponse'
                title: Response Get Collection Preview Url Collections  Collection Id  Preview Url Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/versions:
    get:
      summary: Get Collection Versions
      operationId: get_collection_versions_collections__collection_id__versions_get
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiteCollectionVersionDto'
                title: Response Get Collection Versions Collections  Collection Id  Versions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/update_version:
    put:
      summary: Update Collection Version
      operationId: update_collection_version_collections__collection_id__update_version_put
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiteCollectionVersionTableUpdateInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiteCollectionVersionDto'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/delete_version/{version}:
    delete:
      summary: Delete Collection Version
      operationId: delete_collection_version_collections__collection_id__delete_version__version__delete
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: version
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Version
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /collections/{collection_id}/publish_version/{version}:
    put:
      summary: Publish Collection Version
      operationId: publish_collection_version_collections__collection_id__publish_version__version__put
      security:
      - Auth0: []
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          title: Collection Id
      - name: merchant_id
        in: query
        required: true
        schema:
          type: string
          title: Merchant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiteCollectionPublishVersionInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Collections
  /api/v1/merchants/{merchant_id}/collections:
    get:
      tags:
      - Collections
      summary: List Collections Endpoint
      operationId: list_collections_endpoint_api_v1_merchants__merchant_id__collections_get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: collection_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CollectionType'
          - type: 'null'
          title: Collection Type
      - name: parent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Id
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Search
      - name: sort_by
        in: query
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/CollectionListSortBy'
          default: updated_at_desc
          title: Sort By
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: include_metrics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Metrics
      - name: locale
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionListResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/merchants/{merchant_id}/collections/favourites:
    get:
      tags:
      - Collections
      summary: List Collection Favourites Endpoint
      operationId: list_collection_favourites_endpoint_api_v1_merchants__merchant_id__collections_favourites_get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: include_metrics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Metrics
      - name: locale
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionFavouritesResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/merchants/{merchant_id}/collections/{collection_id}/favourite:
    put:
      tags:
      - Collections
      summary: Add Collection Favourite Endpoint
      operationId: add_collection_favourite_endpoint_api_v1_merchants__merchant_id__collections__collection_id__favourite_put
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Collection Id
      responses:
        '204':
          description: Successful Response
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Collections
      summary: Remove Collection Favourite Endpoint
      operationId: remove_collection_favourite_endpoint_api_v1_merchants__merchant_id__collections__collection_id__favourite_delete
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Collection Id
      responses:
        '204':
          description: Successful Response
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/merchants/{merchant_id}/collections/{collection_id}:
    get:
      tags:
      - Collections
      summary: Get Collection Endpoint
      operationId: get_collection_endpoint_api_v1_merchants__merchant_id__collections__collection_id__get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Collection Id
      - name: market
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Market
      - name: locale
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
      - name: market_group_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Market Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDetail'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Collections
      summary: Save Collection Endpoint
      operationId: save_collection_endpoint_api_v1_merchants__merchant_id__collections__collection_id__patch
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Collection Id
      - name: locale
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionSaveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/merchants/{merchant_id}/collections/{collection_id}/curation:
    get:
      tags:
      - Collections
      summary: Get Collection Curation Endpoint
      operationId: get_collection_curation_endpoint_api_v1_merchants__merchant_id__collections__collection_id__curation_get
      security:
      - Auth0: []
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
          title: Merchant Id
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Collection Id
      - name: market
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Market
      - name: include_auto_hidden
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Auto Hidden
      - name: include_metrics
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Metrics
      - name: locale
        in: query
        required: false
        schema:
          a

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