openapi: 3.0.1
info:
  title: Coveo Activity Activities Recommendations API
  description: API for Coveo Platform
  termsOfService: https://www.coveo.com/en/support/terms-agreements
  contact:
    name: Coveo
    url: https://connect.coveo.com/s/discussions
  version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
  description: Coveo public API endpoint
security:
- oauth2:
  - full
tags:
- name: Recommendations
paths:
  /rest/organizations/{organizationId}/commerce/v2/recommendations:
    post:
      tags:
      - Recommendations
      summary: Execute a Recommendations Query
      description: 'Returns products linked to a recommendations slot.</br></br>**Required privilege:** Execute Query<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}

        ```

        </details>'
      operationId: recommendations
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendationsRequestModel_V2ProductView'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RecommendationsResponseModel_V2ProductView'
      x-pretty-name: recommendations
      x-required-privilege:
        owner: SEARCH_API
        targetDomain: EXECUTE_QUERY
        targetId: '*'
      x-required-privileges:
      - owner: SEARCH_API
        targetDomain: EXECUTE_QUERY
        targetId: '*'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations_post
  /rest/organizations/{organizationId}/commerce/v2/recommendations/preview:
    post:
      tags:
      - Recommendations
      summary: Preview a Recommendations Query
      description: 'Returns a preview response of products linked to a recommendations slot.</br></br>**Required privilege:** Execute Query<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}

        ```

        </details>'
      operationId: recommendationsPreview
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendationsPreviewRequestModel_V2ProductView'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PreviewResponseModel_V2ProductView'
      x-pretty-name: recommendationsPreview
      x-required-privilege:
        owner: SEARCH_API
        targetDomain: EXECUTE_QUERY
        targetId: '*'
      x-required-privileges:
      - owner: SEARCH_API
        targetDomain: EXECUTE_QUERY
        targetId: '*'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/preview_post
components:
  schemas:
    QueryCorrectionResponse_V2ProductView:
      type: object
      properties:
        originalQuery:
          type: string
          description: If the query was automatically corrected, this property indicates the original basic query expression (q) that triggered the automatic query correction.
        correctedQuery:
          type: string
          description: If the query was automatically corrected, this property indicates the corrected basic query expression (q) that was executed instead of the original one.
        corrections:
          type: array
          description: If the query wasn't automatically corrected, this property contains the basic query expression (q) keyword corrections provided by the Did You Mean index feature.
          example:
          - correctedQuery: Coveo Cloud V2 platform
            wordCorrections:
            - correctedWord: platform
              length: 8
              offset: 15
              originalWord: plattfomr
          items:
            $ref: '#/components/schemas/QueryCorrection_V2ProductView'
      description: The query correction response, if the query was corrected.
    PreviewResponseExecutionReportsModel_V2ProductView:
      type: object
      description: The execution reports for a preview query.
      example:
        current:
          children:
          - name: RequestId
            description: The id correlating logs for this request
            duration: 0
            result: null
            X-Request-ID: 948cf669-43ae-4d8d-b285-9b66350c5433
          - name: Organization ID
            description: Organization ID
            duration: 0
            result: null
            coveo_organization: barcasportsmcy01fvu
          duration: 88
        modified:
          children:
          - name: RequestId
            description: The id correlating logs for this request
            duration: 0
            result: null
            X-Request-ID: 148cf689-63ae-4d8d-b285-9b63350c5433
          - name: Organization ID
            description: Organization ID
            duration: 0
            result: null
            coveo_organization: barcasportsmcy01fvu
          duration: 86
    PreviewResult_V2ProductView:
      required:
      - resultType
      type: object
      properties:
        resultType:
          type: string
      description: Preview result item that can be a product or spotlight content (including placeholders)
      discriminator:
        propertyName: resultType
    BadgeViewModel_V2ProductView:
      type: object
      properties:
        text:
          type: string
          description: The localized text displayed on the badge.
          example: Bestseller!
        backgroundColor:
          type: string
          description: The badge background color in the format `#RRGGBB`.
          example: '#FFFFFF'
        textColor:
          type: string
          description: The badge text color in the format `#RRGGBB`.
          example: '#000000'
        iconUrl:
          type: string
          description: The url of an icon to render with the badge text.
          example: https://example.com/icon.png
      description: The list of badges associated with this placement
    RecommendationsRequestModel_V2ProductView:
      required:
      - context
      - country
      - currency
      - language
      - slotId
      - trackingId
      type: object
      properties:
        trackingId:
          minLength: 1
          type: string
          description: The unique identifier of the tracking target.
          example: acmecorporation_ca
        language:
          minLength: 1
          type: string
          description: An ISO 639-1 language code.
          example: en
        country:
          minLength: 1
          type: string
          description: An ISO 3166-1 alpha-2 country code.
          example: US
        currency:
          minLength: 1
          type: string
          description: An ISO 4217 currency code.
          example: USD
        clientId:
          type: string
          description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries, then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf you have a custom Coveo implementation, you will have to generate a [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)>)-formatted GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning models may use this information to provide contextually relevant output.
          example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
        page:
          minimum: 0
          type: integer
          description: The page of products to request.
          format: int32
          example: 7
        perPage:
          maximum: 1000
          minimum: 1
          type: integer
          description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
          format: int32
          example: 30
        debug:
          type: boolean
          description: Whether to include the execution report on a successful response.
          example: true
        slotId:
          type: string
          description: The slot identifier
          format: uuid
          example: 77f997a1-5143-490e-aeff-f219c7718c5f
        context:
          $ref: '#/components/schemas/RecommendationsContextModel_V2ProductView'
      description: The recommendations query to be executed.
    Product_V2ProductView:
      type: object
      allOf:
      - $ref: '#/components/schemas/Result_V2ProductView'
      - type: object
        properties:
          additionalFields:
            type: object
            additionalProperties:
              type: object
              description: The product additional fields.
              example:
                size: M
                material: cotton
            description: The product additional fields.
            example:
              size: M
              material: cotton
          queryPinned:
            type: boolean
            description: Indicates whether the product was pinned by a reserved position rule.
            example: true
          badgePlacements:
            type: array
            description: The list of badge placements associated with this product.
            items:
              $ref: '#/components/schemas/BadgePlacementViewModel_V2ProductView'
          ec_name:
            type: string
            description: The product name.
            example: ACME T-Shirt.
          ec_description:
            type: string
            description: The product description.
            example: A very nice T-Shirt. Comes in blue and green colors.
          ec_shortdesc:
            type: string
            description: The product short description.
            example: A very nice T-Shirt.
          ec_brand:
            type: string
            description: The product brand.
            example: ACME
          ec_category:
            type: array
            description: The product category.
            example:
            - T-Shirts
            items:
              type: string
              description: The product category.
              example: '["T-Shirts"]'
          ec_thumbnails:
            type: array
            description: The product thumbnails.
            example:
            - https://example.com/thumbnail1.jpg
            - https://example.com/thumbnail2.jpg
            items:
              type: string
              description: The product thumbnails.
              example: '["https://example.com/thumbnail1.jpg","https://example.com/thumbnail2.jpg"]'
          ec_images:
            type: array
            description: The product images.
            example:
            - https://example.com/image1.jpg
            - https://example.com/image2.jpg
            items:
              type: string
              description: The product images.
              example: '["https://example.com/image1.jpg","https://example.com/image2.jpg"]'
          ec_price:
            type: number
            description: The product price.
            format: double
            example: 19.99
          ec_promo_price:
            type: number
            description: The product promotional price.
            format: double
            example: 14.99
          ec_in_stock:
            type: boolean
            description: The product availability.
            example: true
          ec_item_group_id:
            type: string
            description: The product item group identifier.
            example: '0000003035'
          ec_rating:
            type: number
            description: The product rating.
            format: double
            example: 4.5
          ec_product_id:
            type: string
            description: The product identifier.
            example: 0000003035-45
          ec_gender:
            type: string
            description: The intended gender of the product user.
            example: M
          ec_color:
            type: string
            description: The product color.
            example: Blue
          ec_listing:
            type: string
            description: The product listing.
            example: T-Shirt
          clickUri:
            type: string
            description: The product click URI.
            example: https://example.com/product/0000003035-45
          permanentid:
            type: string
            description: The product permanent identifier.
            example: 0000003035-45
          children:
            type: array
            description: The product child results.
            items:
              $ref: '#/components/schemas/ChildProduct_V2ProductView'
          totalNumberOfChildren:
            type: integer
            description: The total number of child results.
            format: int32
            example: 2
    RecommendationsContextModel_V2ProductView:
      required:
      - view
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserModel_V2ProductView'
        view:
          $ref: '#/components/schemas/ViewModel_V2ProductView'
        cart:
          type: array
          description: The cart information.
          items:
            $ref: '#/components/schemas/CartItemModel_V2ProductView'
        source:
          type: array
          description: Defines one or more client side libraries that generated the analytics event. The format should be the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
          example:
          - '@coveo/headless@2.61.0'
          - custom.library.js@2.0.0
          items:
            minLength: 1
            pattern: ^[^@]*@.*$
            type: string
            description: A context source
            example: '@coveo/headless@2.61.0'
        capture:
          type: boolean
          description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`, this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
          example: true
        labels:
          type: object
          additionalProperties:
            type: string
            description: Deprecated - The context labels.
            example: '{"category":"garden > garden-tools > chainsaws","brand":"ACME"}'
          description: Deprecated - The context labels.
          example:
            category: garden > garden-tools > chainsaws
            brand: ACME
        custom:
          type: object
          additionalProperties:
            type: object
            description: Custom context values under context.custom. Use this for context mapping.
            example:
              fitmentProducts:
              - sku_123
              - sku_456
          description: Custom context values under context.custom. Use this for context mapping.
          example:
            fitmentProducts:
            - sku_123
            - sku_456
        product:
          $ref: '#/components/schemas/ProductItemModel_V2ProductView'
        purchased:
          type: array
          description: The purchased product IDs and quantity used to generate the recommendations.
          items:
            $ref: '#/components/schemas/CartItemModel_V2ProductView'
      description: Contextual information about the query.
    ProductItemModel_V2ProductView:
      type: object
      properties:
        productId:
          type: string
          description: The id of the product.
          example: shoe-a1-red
      description: The product ID used to generate the recommendations.
    RecommendationsResponseModel_V2ProductView:
      type: object
      properties:
        responseId:
          type: string
          description: The unique identifier of the API response. It can be attached to any subsequent impression or click event to attribute them to the request.
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        headline:
          type: string
          description: The recommendations slot headline.
          example: Recommended for you
        products:
          type: array
          description: The subset of products returned by the query.
          items:
            oneOf:
            - $ref: '#/components/schemas/Product_V2ProductView'
            - $ref: '#/components/schemas/ChildProduct_V2ProductView'
            - $ref: '#/components/schemas/ProductForPreview_V2ProductView'
        pagination:
          $ref: '#/components/schemas/PaginationResponseModel_V2ProductView'
        triggers:
          type: array
          description: The actions for the client to perform based on the Trigger statements defined.
          example:
          - type: redirect
            content: https://www.example.com
          items:
            $ref: '#/components/schemas/TriggerModel_V2ProductView'
    UserModel_V2ProductView:
      type: object
      properties:
        userAgent:
          type: string
          description: 'The user agent of the request. If not present, the user agent is obtained from the [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) header.\n\n**Note**: This information is required when endpoints are behind a proxy.'
          example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36
      description: The user information.
    PreviewResponseIdsModel_V2ProductView:
      type: object
      properties:
        current:
          type: string
          description: The unique identifier of the API response. It can be attached to any subsequent impression or click event to attribute them to the request.
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        modified:
          type: string
          description: The unique identifier of the API response. It can be attached to any subsequent impression or click event to attribute them to the request.
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
      description: The unique identifiers of the API responses for a preview request.
      example:
        current: 123e4567-e89b-12d3-a456-426614174000
        modified: 94c3779c-0e42-40b5-95b8-93a6ed3ea162
    ViewModel_V2ProductView:
      required:
      - url
      type: object
      properties:
        url:
          minLength: 1
          type: string
          description: The URL used to retrieve the products. Used as `documentLocation` for analytics purposes, which indicates the URL of the resource where the request originated.
          example: https://acme.com/summersale
        referrer:
          type: string
          description: Typically the URL of the page that linked to the interface from which the request originates (e.g., in JavaScript, this would correspond to the `document.referrer` value).\n\nCoveo Machine Learning models may use this information to provide contextually relevant output. Used as `documentReferrer` for analytics purposes.
          nullable: true
          example: https://example.com/
      description: 'A collection of data points describing the view. Note: The term ''view'' is used instead of ''page'' to accommodate usage in contexts such as mobile apps.'
    QueryCorrection_V2ProductView:
      type: object
      properties:
        correctedQuery:
          type: string
          description: The resulting query expression correction suggestion.
        wordCorrections:
          type: array
          description: The word correction suggestions.
          items:
            $ref: '#/components/schemas/WordCorrection_V2ProductView'
      description: If the query wasn't automatically corrected, this property contains the basic query expression (q) keyword corrections provided by the Did You Mean index feature.
      example:
      - correctedQuery: Coveo Cloud V2 platform
        wordCorrections:
        - correctedWord: platform
          length: 8
          offset: 15
          originalWord: plattfomr
    PreviewResponseModel_V2ProductView:
      type: object
      properties:
        products:
          type: array
          description: The subset of products returned by the query.
          items:
            $ref: '#/components/schemas/ProductForPreview_V2ProductView'
        results:
          type: array
          description: List of results including products and spotlight content
          items:
            $ref: '#/components/schemas/PreviewResult_V2ProductView'
        pagination:
          $ref: '#/components/schemas/PaginationResponseModel_V2ProductView'
        responseIds:
          $ref: '#/components/schemas/PreviewResponseIdsModel_V2ProductView'
        executionReports:
          $ref: '#/components/schemas/PreviewResponseExecutionReportsModel_V2ProductView'
        queryCorrection:
          $ref: '#/components/schemas/QueryCorrectionResponse_V2ProductView'
    Result_V2ProductView:
      required:
      - resultType
      type: object
      properties:
        resultType:
          type: string
      description: List of results including products and spotlight content
      discriminator:
        propertyName: resultType
    ChildProduct_V2ProductView:
      type: object
      allOf:
      - $ref: '#/components/schemas/Product_V2ProductView'
      - $ref: '#/components/schemas/Result_V2ProductView'
    CartItemModel_V2ProductView:
      type: object
      properties:
        productId:
          type: string
          description: The id of the product.
          example: shoe-a1-red
        quantity:
          type: integer
          description: The product quantity.
          format: int32
          example: 2
      description: A purchased item.
    TriggerModel_V2ProductView:
      type: object
      properties:
        type:
          type: string
          description: The type of trigger.
          example: redirect
          enum:
          - execute
          - notify
          - redirect
          - query
        content:
          type: string
          description: The content of the trigger.
          example: https://www.example.com
      description: The actions for the client to perform based on the Trigger statements defined.
      example:
      - type: redirect
        content: https://www.example.com
    BadgePlacementViewModel_V2ProductView:
      type: object
      properties:
        placementId:
          type: string
          description: The placement unique identifier.
          format: uuid
          example: 36164bca-b489-4c42-8574-e1325d56d0be
        badges:
          type: array
          description: The list of badges associated with this placement
          items:
            $ref: '#/components/schemas/BadgeViewModel_V2ProductView'
      description: The list of badge placements associated with this product.
    PaginationResponseModel_V2ProductView:
      type: object
      properties:
        page:
          type: integer
          description: The page of products to request.
          format: int32
          example: 7
        perPage:
          type: integer
          description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
          format: int32
          example: 30
        totalEntries:
          type: integer
          description: The total number of results that match the query.
          format: int32
          example: 100
        totalPages:
          type: integer
          description: The total number of pages of items available.
          format: int32
          example: 10
        totalProducts:
          type: integer
          description: The total number of products that match the query.
          format: int32
          example: 90
        totalSpotlightContent:
          type: integer
          description: The total number of spotlight content that match the query.
          format: int32
          example: 10
      description: Contextual pagination information about the query.
      example:
        page: 1
        perPage: 10
        totalPages: 10
        totalEntries: 100
    WordCorrection_V2ProductView:
      type: object
      properties:
        correctedWord:
          type: string
          description: The suggested word correction.
        length:
          type: integer
          description: The length (in number of characters) of the corrected word.
          format: int32
        offset:
          type: integer
          description: The offset (in number of characters) of the corrected word, from the beginning of the resulting query expression correction suggestion.
          format: int32
        originalWord:
          type: string
          description: The original, un-corrected word.
      description: The word correction suggestions.
    RecommendationsPreviewRequestModel_V2ProductView:
      required:
      - country
      - currency
      - language
      - strategy
      - trackingId
      type: object
      properties:
        slotId:
          type: string
          description: The slot identifier
          format: uuid
          example: 77f997a1-5143-490e-aeff-f219c7718c5f
        trackingId:
          minLength: 1
          type: string
          description: The unique identifier of the tracking target.
          example: acmecorporation_ca
        language:
          minLength: 1
          type: string
          description: An ISO 639-1 language code.
          example: en
        country:
          minLength: 1
          type: string
          description: An ISO 3166-1 alpha-2 country code.
          example: US
        currency:
          minLength: 1
          type: string
          description: An ISO 4217 currency code.
          example: USD
        page:
          minimum: 0
          type: integer
          description: The page of products to request.
          format: int32
          example: 7
        perPage:
          maximum: 1000
          minimum: 1
          type: integer
          description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
          format: int32
          example: 30
          default: 30
        products:
          type: array
          description: The product IDs used to generate the recommendations.
          items:
            $ref: '#/components/schemas/ProductItemModel_V2ProductView'
        strategy:
          type: string
          description: The [strategy](https://docs.coveo.com/en/3132/glossary/product-recommendations) to use for recommendations.
          example: popular_bought
          enum:
          - bought_together
          - popular_bought
          - popular_viewed
          - viewed_together
        debug:
          type: boolean
          description: Whether to include the execution report on a successful response.
          example: true
        minRecs:
          maximum: 100
          minimum: 1
          type: integer
          description: Products to be returned.
          format: int32
      description: The recommendations query to be executed.
    ProductForPreview_V2ProductView:
      type: object
      allOf:
      - $ref: '#/components/schemas/Product_V2ProductView'
      - type: object
        properties:
          score:
            type: integer
            description: The total ranking score computed for the product.
            format: int32
            example: 1292
          scoreDifference:
            type: integer
            description: Score difference between the cached and previewed rules for a product.
            format: int32
            example: 1292
          positionDifference:
            type: integer
            description: Position difference between the cached and previewed rules for a product.
            format: int32
            example: 9
          included:
            type: boolean
            description: Whether the product has been included or not after applying a rule.
          pinned:
            type: boolean
            description: Whether the product has been pinned or not after applying a rule.
          reservedPosition:
            type: boolean
            description: Whether the product is in a position that is reserved for a query-time pin.
      - $ref: '#/components/schemas/Result_V2ProductView'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize
          tokenUrl: https://platform.cloud.coveo.com/oauth/token
          scopes:
            full: required