Coveo Search API

openapi: 3.0.1
info:
  title: Coveo Activity Activities Search 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: Search
paths:
  /rest/organizations/{organizationId}/commerce/v2/search:
    post:
      tags:
      - Search
      summary: Execute a Search Query
      description: 'Returns products linked to a user query and merchandiser defined hub.</br></br>**Required privilege:** Execute Query<br /><br /><details><summary>Privilege required</summary>

        ```

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

        ```

        </details>'
      operationId: search
      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/SearchRequestModel_V2SearchProductView'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SearchResponseModel_V2SearchProductView'
      x-pretty-name: search
      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/search_post
  /rest/organizations/{organizationId}/commerce/v2/search/redirect:
    post:
      tags:
      - Search
      summary: Execute a Search Redirect Query
      description: 'Returns a redirect linked to a user query and merchandiser defined hub.</br></br>**Required privilege:** Execute Query<br /><br /><details><summary>Privilege required</summary>

        ```

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

        ```

        </details>'
      operationId: redirect
      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/SearchRedirectRequestModel_V2SearchProductView'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SearchRedirectResponseModel_V2SearchProductView'
      x-pretty-name: redirect
      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/search/redirect_post
  /rest/organizations/{organizationId}/commerce/v2/search/querySuggest:
    post:
      tags:
      - Search
      summary: Request Query Suggestions
      description: 'Returns query suggestions.</br></br>**Required privilege:** Execute Query<br /><br /><details><summary>Privilege required</summary>

        ```

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

        ```

        </details>'
      operationId: querySuggest
      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/QuerySuggestRequestModel'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/QuerySuggestResponseModel'
      x-pretty-name: querySuggest
      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/search/querySuggest_post
  /rest/organizations/{organizationId}/commerce/v2/search/productSuggest:
    post:
      tags:
      - Search
      summary: Request Product Suggestions
      description: 'Returns product suggestions.</br></br>**Required privilege:** Execute Query<br /><br /><details><summary>Privilege required</summary>

        ```

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

        ```

        </details>'
      operationId: productSuggest
      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/SearchRequestModel_V2SearchProductView'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SearchResponseModel_V2SearchProductView'
      x-pretty-name: productSuggest
      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/search/productSuggest_post
components:
  schemas:
    PaginationResponseModel_V2SearchProductView:
      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
    CartItemModel:
      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 cart item.
    HierarchicalFacetResultValue_V2SearchProductView:
      type: object
      properties:
        state:
          type: string
          enum:
          - idle
          - selected
        numberOfResults:
          type: integer
          format: int64
        isAutoSelected:
          type: boolean
        isSuggested:
          type: boolean
        moreValuesAvailable:
          type: boolean
          description: Whether additional facet values matching the request are available.
        value:
          type: string
          description: This represents a single path segment.
        path:
          type: array
          items:
            type: string
        isLeafValue:
          type: boolean
        children:
          type: array
          description: The children of this hierarchical facet value.
          items:
            $ref: '#/components/schemas/HierarchicalFacetResultValue_V2SearchProductView'
    Completion:
      type: object
      properties:
        expression:
          type: string
          description: The query suggestion expression.
          example: albert camus
        highlighted:
          type: string
          description: The highlighted query suggestion expression.
          example: '[albert] {cam}[us]'
      description: The list of query suggestions.
    QueryCorrection_V2SearchProductView:
      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_V2SearchProductView'
      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
    SortByFieldRequestResponseModel_V2SearchProductView:
      required:
      - field
      type: object
      properties:
        field:
          minLength: 1
          type: string
          description: The name of a field to sort by.
        direction:
          type: string
          description: 'Sort order:<br/>Default: `ascending`<br/><ul><li>`asc` - Ascending, from A to Z</li><li>`desc` - Descending, from Z to A</li></ul>'
          enum:
          - asc
          - desc
        displayName:
          type: string
          description: The display name of a field.
      description: Defines the fields and, optionally, their sort order.
    HierarchicalValueModel_V2SearchProductView:
      required:
      - value
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting facet values.
        value:
          minLength: 1
          type: string
          description: This represents a single path segment.
        children:
          type: array
          description: The children of this hierarchical facet value.
          items:
            $ref: '#/components/schemas/HierarchicalValueModel_V2SearchProductView'
        retrieveCount:
          type: integer
          description: The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren is false.
          format: int32
      description: The values displayed by the facet in the search interface at the moment of the request.
    DateRangeValueModel_V2SearchProductView:
      required:
      - end
      - start
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting facet values.
        start:
          minLength: 1
          type: string
          description: The value to start the range at.
        end:
          minLength: 1
          type: string
          description: The value to end the range at. Must be greater (or later) than the start value.
        endInclusive:
          type: boolean
          description: Whether to include the end value in the range.
      description: The values displayed by the facet in the search interface at the moment of the request.
    UserModel_V2SearchProductView:
      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.
    NumericalRangeValueModel_V2SearchProductView:
      required:
      - end
      - start
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting facet values.
        start:
          type: number
          description: The value to start the range at.
        end:
          type: number
          description: The value to end the range at. Must be greater (or later) than the start value.
        endInclusive:
          type: boolean
          description: Whether to include the end value in the range. It should typically be set to the value last received in the `endInclusive` property of the facet response.
      description: The values displayed by the facet in the search interface at the moment of the request.
    SpotlightContentModel_V2SearchProductView:
      required:
      - clickUri
      - desktopImage
      type: object
      description: Spotlight Content
      allOf:
      - $ref: '#/components/schemas/Result_V2SearchProductView'
      - type: object
        properties:
          id:
            type: string
            description: The unique identifier of the spotlight content
            format: uuid
            readOnly: true
            example: 123e4567-e89b-12d3-a456-426614174000
          name:
            maxLength: 255
            minLength: 1
            type: string
            description: The name of the spotlight content
            example: Summer Sale
          description:
            maxLength: 255
            minLength: 1
            type: string
            description: The description of the spotlight content
            example: Get up to 50% off on summer items
          clickUri:
            maxLength: 1024
            minLength: 1
            type: string
            description: The click URI for the spotlight content
            example: https://example.com/summer-sale
          desktopImage:
            maxLength: 1024
            minLength: 1
            type: string
            description: The desktop image URL for the spotlight content
            example: https://example.com/images/summer-sale-desktop.jpg
          mobileImage:
            maxLength: 1024
            minLength: 1
            type: string
            description: The mobile image URL for the spotlight content
            example: https://example.com/images/summer-sale-mobile.jpg
          nameFontColor:
            type: string
            description: The font color for the name text in the format `#RRGGBB`.
            example: '#000000'
          descriptionFontColor:
            type: string
            description: The font color for the description text in the format `#RRGGBB`.
            example: '#000000'
          altText:
            maxLength: 255
            minLength: 1
            type: string
            description: The alt text for the spotlight content image for accessibility
            example: Summer sale promotional banner
    SortByRelevanceRequestResponseModel_V2SearchProductView:
      type: object
      allOf:
      - $ref: '#/components/schemas/AbstractSortRequestResponseModel_V2SearchProductView'
    ViewModel:
      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.'
    QuerySuggestResponseModel:
      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
        completions:
          type: array
          description: The list of query suggestions.
          items:
            $ref: '#/components/schemas/Completion'
    ContextModel:
      required:
      - view
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserModel'
        view:
          $ref: '#/components/schemas/ViewModel'
        cart:
          type: array
          description: The cart information.
          items:
            $ref: '#/components/schemas/CartItemModel'
        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
      description: Contextual information about the query.
    WordCorrection_V2SearchProductView:
      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.
    BadgeViewModel_V2SearchProductView:
      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
    LegacyFacetOptions_V2SearchProductView:
      type: object
      properties:
        freezeFacetOrder:
          type: boolean
          description: 'Default: `false`<br/>Whether facets should be returned in the same order in which they were requested.'
      description: Facet Options for legacy (v1) facets.
    Product_V2SearchProductView:
      type: object
      allOf:
      - $ref: '#/components/schemas/Result_V2SearchProductView'
      - 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_V2SearchProductView'
          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
          nameHighlights:
            type: array
            description: The product name highlights.
            example:
            - ACME
            - T-Shirt
            items:
              $ref: '#/components/schemas/Highlight_V2SearchProductView'
          excerpt:
            type: string
            description: The product exerts.
            example: The T-Shirt is very nice
          excerptHighlights:
            type: array
            description: The product exerts highlights.
            items:
              $ref: '#/components/schemas/Highlight_V2SearchProductView'
          children:
            type: array
            description: The product child results.
            items:
              $ref: '#/components/schemas/ChildProduct_V2SearchProductView'
          totalNumberOfChildren:
            type: integer
            description: The total number of child results.
            format: int32
            example: 2
    RequestFacetBaseObject_V2SearchProductView:
      required:
      - field
      - values
      type: object
      properties:
        facetId:
          type: string
          description: Name of the field to execute the facet search request against.
          example: color
        field:
          minLength: 1
          type: string
          description: The facet field name.
          example: ec_brand
        displayName:
          type: string
          description: The facet display name.
          example: Brand
        values:
          minItems: 1
          type: array
          description: The values displayed by the facet in the search interface at the moment of the request.
          items:
            type: object
            description: The values displayed by the facet in the search interface at the moment of the request.
        numberOfValues:
          type: object
          properties:
            empty:
              type: boolean
            present:
              type: boolean
            asInt:
              type: integer
              format: int32
          description: 'The maximum number of facet values to fetch. It should typically be set to the value last received

            in the `numberOfValues` property of the facet response.

            <br/>

            <br/>

            An exception to this guideline is the case where the last response had

            `moreValuesAvailable=true` and the user asks to see more values for this facet. In this case,

            the front-end is expected to send a value greater than the `numberOfValues` that it last received

            in the response. This ensures that more values are fetched from the index.

            <br/>

            <br/>

            When not provided, the default number of values configured for this facet is used.

            '
        type:
          type: string
          description: 'One of: `regular`, `dateRange`, `numericalRange`, `hierarchical`. For more information, see the [facet types](https://docs.coveo.com/en/p3oa0420#facet-types) documentation.'
          enum:
          - regular
          - dateRange
          - numericalRange
          - hierarchical
          - regular
      description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest' endpoint.
      example:
      - field: ec_category
        type: regular
        values:
        - value: shoes
          state: idle
      discriminator:
        propertyName: type
    UserModel:
      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.
    ContextModel_V2SearchProductView:
      required:
      - view
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserModel_V2SearchProductView'
        view:
          $ref: '#/components/schemas/ViewModel_V2SearchProductView'
        cart:
          type: array
          description: The cart information.
          items:
            $ref: '#/components/schemas/CartItemModel_V2SearchProductView'
        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
      description: Contextual information about the query.
    NumericalRangeFacetModel_V2SearchProductView:
      required:
      - field
      - values
      type: object
      description: Numerical range facet.
      example:
        facetId: ec_price
        field: ec_price
        displayNames:
        - value: Price
        

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