openapi: 3.0.1
info:
  title: Coveo Activity Activities Machine learning associations 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: Machine learning associations
  x-displayName: Machine learning associations
paths:
  /rest/search/v2/admin/pipelines/{pipelineId}/ml/model/associations:
    get:
      tags:
      - Machine learning associations
      summary: List Query Pipeline ML Model Associations
      description: 'Gets a page of Coveo Machine Learning model associations for a specific query pipeline.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: listAssociationsOfPipeline
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: filter
        in: query
        description: 'Filter associations by model display name or description (case-insensitive substring match).


          For example, `filter=product` will match associations where the model display name or description contains "product".


          By default, all associations are returned when no filter is specified.'
        schema:
          type: string
          maxLength: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssociationWithConditionResponseBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
    post:
      tags:
      - Machine learning associations
      summary: Associate an Existing Machine Learning Model with an Existing Pipeline.
      operationId: associateModel
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      requestBody:
        description: 'The configuration options to apply to the ML model.


          The `cacheMaximumAge, `condition`, `description`, and `maxResults`, options apply to all types of models. Other configuration options are only taken into account for specific types of models:


          - `enableWordCompletion`: query suggestions

          - `exclusive`: event recommendations

          - `intelligentTermDetection`, `matchAdvancedQuery`, and `matchQuery`: automatic relevance tuning

          - `rankingModifier`: automatic relevance tuning, event recommendations'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssociationRequest'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
      description: '<details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}

        ```

        </details>'
  /rest/search/v2/admin/pipelines/{pipelineId}/ml/model/associations/{associationId}:
    get:
      tags:
      - Machine learning associations
      summary: Get a ML Model Association
      description: 'Gets a Coveo Machine Learning model association.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: getAssociation
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      - name: associationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MlPipelineAssociationWithGroupAndCondition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
    put:
      tags:
      - Machine learning associations
      summary: Update ML Model Association
      description: 'Changes the configuration of an association in a pipeline.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}

        ```

        </details>'
      operationId: updateAssociation
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      - name: associationId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: 'The configuration options to apply to the ML model.


          The `cacheMaximumAge`, `condition`, `description`, and `maxResults`, options apply to all types of models. Other configuration options are only taken into account for specific types of models:


          - `enableWordCompletion`: query suggestions

          - `exclusive`: event recommendations

          - `intelligentTermDetection`, `matchAdvancedQuery`, and `matchQuery`: automatic relevance tuning

          - `rankingModifier`: automatic relevance tuning, event recommendations'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditAssociationRequest'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '204':
          description: No Content
          content: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
    delete:
      tags:
      - Machine learning associations
      summary: Remove Query Pipeline ML Model Association
      description: 'Removes a single existing association between a machine learning model and a query pipeline.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}

        ```

        </details>'
      operationId: disassociate
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      - name: associationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '204':
          description: No Content
          content: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
  /rest/search/v2/admin/pipelines/{pipelineId}/ml/model/associations/{associationId}/position:
    put:
      tags:
      - Machine learning associations
      summary: Update ML Model Association Position
      description: 'Changes the position of an association in a pipeline.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}

        ```

        </details>'
      operationId: updateAssociationPosition
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      - name: associationId
        in: path
        required: true
        schema:
          type: string
      - name: position
        in: query
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '204':
          description: No Content
          content: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
  /rest/search/v2/admin/pipelines/{pipelineId}/ml/model/associations/bulkGet:
    post:
      tags:
      - Machine learning associations
      summary: List Query Pipeline ML Model Associations
      description: 'Gets a page of Coveo Machine Learning model associations for a specific query pipeline.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: bulkGetAssociationsOfPipeline
      parameters:
      - $ref: '#/components/parameters/PipelineIdPath'
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      requestBody:
        description: A set of parameters to customize the results.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestBulkGetRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssociationWithConditionResponseBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
  /rest/search/v2/admin/pipelines/{pipelineId}/ml/model/associations/validate:
    post:
      tags:
      - Machine learning associations
      summary: Validate a Single ML Model Association Operation.
      description: 'Validate that a specific operation would be accepted by our API and executed.

        <details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: validateMlAssociationOperation
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      requestBody:
        description: An object that contains an operation to validate.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssociationSingleValidationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestSingleOperationValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
  /rest/search/v2/admin/pipelines/{pipelineId}/ml/model/associations/validate/batch:
    post:
      tags:
      - Machine learning associations
      summary: Validate a Batch of ML Model Association Operations.
      description: "\n Validate that a list of operations would be accepted by our API and executed.\n A maximum of 15 can be processed per request.\n<details>\n<summary>Privilege(s) required</summary>\n\n```json\n{\"level\":\"NORMAL\",\"owner\":\"SEARCH_API\",\"targetDomain\":\"QUERY_PIPELINE\",\"type\":\"VIEW\",\"targetId\":\"*\"}\n```\n</details>"
      operationId: validateMlAssociationOperations
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      - $ref: '#/components/parameters/PipelineIdPath'
      requestBody:
        description: An object that contains the list of operations to validate.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssociationBatchValidationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestBatchOperationValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - oauth2:
        - full
  /rest/search/v2/admin/pipelines/ml/version:
    get:
      tags:
      - Machine learning associations
      summary: Returns the Version of ML Models Supported by the Organization in the Request.
      operationId: mlVersion
      parameters:
      - $ref: '#/components/parameters/OrganizationIdQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '419':
          $ref: '#/components/responses/AuthenticationTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - oauth2:
        - full
      description: '<details>

        <summary>Privilege(s) required</summary>


        ```json

        {"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}

        ```

        </details>'
components:
  schemas:
    RestBatchOperationValidationResponse:
      required:
      - results
      type: object
      properties:
        results:
          type: array
          description: The list of operation validation results.
          items:
            $ref: '#/components/schemas/RestOperationValidationResponse'
    MlPipelineAssociationWithGroupAndCondition:
      type: object
      required:
      - id
      - position
      - modelId
      - modelStatus
      properties:
        id:
          type: string
        position:
          type: integer
          minimum: 0
        modelId:
          type: string
        modelDisplayName:
          type: string
        modelEngine:
          type: string
        modelStatus:
          type: string
        condition:
          type: string
        conditionDefinition:
          type: string
        rankingModifier:
          type: integer
        maxRecommendations:
          type: integer
        exclusive:
          type: boolean
        enableWordCompletion:
          type: boolean
        intelligentTermDetection:
          type: boolean
        intelligentTermDetectionPartialMatchThreshold:
          type: string
        intelligentTermDetectionPartialMatchKeywords:
          type: integer
        matchBasicExpression:
          type: boolean
        matchAdvancedExpression:
          type: boolean
        customQueryParameters:
          type: object
          additionalProperties: true
        useAdvancedConfiguration:
          type: boolean
        dynamicNavigationExperience:
          type: object
        associatedGroup: {}
        contentIdKeys:
          type: array
          items:
            type: string
        description:
          type: string
        passageRetrieval:
          $ref: '#/components/schemas/PassageRetrievalConfiguration'
    RestBulkGetRequest:
      type: object
      properties:
        ids:
          type: array
          description: A list of resource identifiers to get. A maximum of **1000** can be sent.
          items:
            type: string
            maxItems: 1000
    AssociationBatchValidationRequest:
      required:
      - operations
      type: object
      properties:
        operations:
          type: array
          description: A list of operations to validate.
          example:
          - operationType: CREATE
            model: {}
          - operationType: UPDATE
            model: {}
            resourceId: resource-id
          - operationType: DELETE
            resourceId: resource-id
          items:
            $ref: '#/components/schemas/AssociationValidationRequest'
    AssociationSingleValidationRequest:
      required:
      - operation
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/AssociationValidationRequest'
    RestSingleOperationValidationResponse:
      required:
      - result
      type: object
      properties:
        result:
          $ref: '#/components/schemas/RestOperationValidationResponse'
    ErrorMessage:
      type: object
      additionalProperties: true
      properties:
        statusCode:
          type: number
          example: 404
        errorCode:
          type: string
          example: ORGANIZATION_DOES_NOT_EXIST
        message:
          type: string
          example: The organization does not exist in the search api.
    PassageRetrievalConfiguration:
      type: object
      properties:
        numberOfDocumentsToConsider:
          type: integer
          description: The number of documents to consider for passage retrieval.
          format: int32
          minimum: 1
          default: 40
          maximum: 100
    AutomaticSelectionConfiguration:
      type: object
      properties:
        isEnabled:
          type: boolean
          description: Whether to enable automatic facet value selection.
          default: true
    AssociationWithConditionResponseBody:
      required:
      - rules
      - totalEntries
      - totalPages
      type: object
      properties:
        rules:
          type: array
          items:
            $ref: '#/components/schemas/MlPipelineAssociationWithGroupAndCondition'
        totalEntries:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
    RestOperationValidationResponse:
      required:
      - operationType
      - operationValid
      type: object
      properties:
        operationType:
          type: string
          description: The type of operation that has been validated.
          example: CREATE
        operationValid:
          type: boolean
          description: Whether the operation to validate was successful or not.
          example: true
        resourceId:
          type: string
          description: 'The identifier of the resource. '
          example: id
        validationErrors:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/RestOperationValidationError'
          description: If the operation failed, the `validationError` will contains the error message.
          example: Access Denied. You don't have the required privileges to perform  this operation.
    AssociationValidationRequest:
      required:
      - operationType
      type: object
      properties:
        operationType:
          type: string
          description: 'The type of operation to validate. Each operation type has specific validation rules.


            Additional request parameters are required based on the type of operation to validate:

            - `CREATE`: You must provide a `model`.

            - `UPDATE`: You must provide a `model` and a `resourceId`.

            - `DELETE`: You must provide a `resourceId`.

            '
          example: CREATE
          enum:
          - CREATE
          - UPDATE
          - DELETE
        model:
          type: object
          oneOf:
          - $ref: '#/components/schemas/CreateAssociationRequest'
          - $ref: '#/components/schemas/EditAssociationRequest'
        resourceId:
          type: string
          description: 'The identifier of the resource. '
          example: id
    DynamicNavigationExperienceConfiguration:
      type: object
      properties:
        automaticSelection:
          $ref: '#/components/schemas/AutomaticSelectionConfiguration'
    CreateAssociationRequest:
      required:
      - modelId
      type: object
      properties:
        modelId:
          type: string
          description: The unique identifier of the ML model to create an association with.
          example: mycoveocloudorganization_topclicks_My_ART_Model
        rankingModifier:
          type: integer
          description: "The ranking score modifier the ML model should apply to each item it recommends.\n\nUsed by the following ML models:\n  - Automatic relevance tuning (default value: `1000`)\n  - Event recommendation (default value: `1000`)\""
          format: int32
          example: 500
        matchBasicExpression:
          type: boolean
          description: 'Whether all items recommended by the ML model should match the basic query expression (e.g., end-user input in the search box).


            Used by the following ML models:

            - Automatic relevance tuning (default value: `false`)'
        matchAdvancedExpression:
          type: boolean
          description: 'Whether all items recommended by the ML model should match the advanced query expression (e.g., facet selections).


            Used by the following ML models:

            - Automatic relevance tuning (default value: `true`)'
        intelligentTermDetection:
          type: boolean
          description: "Whether the ML model should use the Intelligent Term Detection (ITD) feature to refine queries by extracting relevant keywords from the large query expression and injecting those in the basic query expression.\n  \nUsed by the following ML models:\n- Automatic relevance tuning (default value: `false`)"
        intelligentTermDetectionPartialMatchThreshold:
          type: string
          description: 'An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression refined by the Intelligent Term Detection (ITD) feature.


            If specified, the `intelligentTermDetectionPartialMatchKeywords` value must either be:


            - a number between 1 and 10

            - a percentage value between 1% and 100% (e.g., `75%`)


            **Examples:**


            - `3`

            - `75%`


            **Notes:**


            - This parameter has no meaning unless the `intelligentTermDetection` parameter is set to `true`.


            Used by the following ML model:

            - Automatic relevance tuning (default value: `60%`)'
          example: 75%
          default: 60%
        intelligentTermDetectionPartialMatchKeywords:
          type: integer
          description: 'The minimum number of keywords that need to be present in an Intelligent Term Detection (ITD) response to convert it to a partial match expression.


            **Notes:**


            - This parameter has no meaning unless the `intelligentTermDetection` parameter is set to `true`.


            Used by the following ML model:

            - Automatic relevance tuning (default value: `1`)'
          format: int32
          example: 4
          default: 1
        condition:
          type: string
          description: The unique identifier of the condition that must be satisfied for a request to be processed by the ML model.
          example: 45a7892e-a63f-4c8e-8795-ab38c8c18d7e
        maxRecommendations:
          type: integer
          description: 'The maximum number of recommendations the ML model should return. This should be set to a relatively low value (typically well below 50), otherwise some of the recommended items may not actually be relevant. (Automatic relevance tuning default value: 5. Query suggest default value: 10)'
          format: int32
        cacheMaximumAge:
          type: string
          description: 'The maximum age of cached query results the ML model should accept, in the ISO - 8601 format only including the seconds and milliseconds part. **Default:** `PT1800S`.


            For each incoming query to be processed by the ML model, if a result set for an identical previously made query is available in cache and this result set is not older than the specified value, the ML model makes recommendations based on that cached query result set. Otherwise, the query is executed against the index.'
          example: PT300S
        enableWordCompletion:
          type: boolean
          description: 'Whether the ML model should attempt to complete the last word of the basic query expression and increase the ranking score of the resulting expression so that it is returned as the first completion suggestion.


            Used by the following ML models:

            - Query suggestions (default value: `true`)'
        description:
          type: string
          description: The ML model association description.
        exclusive:
          type: boolean
          description: 'Whether the Search API should only return items which were recommended by the ML model, even if other items matching the query were found in the index.


            Used by the following ML models:

            - Event recommendations (default value: `true`)

            - Product recommendations (default value: `true`)'
        customQueryParameters:
          type: object
          additionalProperties: true
          description: 'The additional parameters to send to Coveo ML.


            Among other things, this can be used to specify the [`strategy`](https://docs.coveo.com/en/p85e0425/) to use when querying a Product Recommendations model (for example, `{ "strategy": "frequentBought" }`. The valid `strategy` values are:


            - `cart`

            - `frequentBought`

            - `frequentViewed`

            - `popularBought`

            - `popularViewed`

            - `recentlyBought`

            - `recentlyViewed`

            - `user`'
        useAdvancedConfiguration:
          type: boolean
          description: '**Internal:** This property is exposed for internal use by the Coveo Cloud administration console.


            Whether the administration console should show the advanced editor for this association.


            **Note:** Properties not supported by the standard editor may not be preserved if managed via direct API calls or the advanced editor.


            **Default:** `false`'
        dynamicNavigationExperience:
          $ref: '#/components/schemas/DynamicNavigationExperienceConfiguration'
        contentIdKeys:
          type: array
          description: 'The names of the fields to use to uniquely identify items in the index.


            **Default:** `["permanentid","urihash"]`'
          items:
            type: string
        statementGroupId:
          type: string
          description: The unique identifier of the statement group.
          example: 679adb80-444e-11ea-b77f-2e728ce88125
        passageRetrieval:
          $ref: '#/components/schemas/PassageRetrievalConfiguration'
    RestOperationValidationError:
      required:
      - message
      type: object
      properties:
        message:
          type: string
    EditAssociationRequest:
      type: object
      properties:
        rankingModifier:
          type: integer
          description: "The ranking score modifier the ML model should apply to each item it recommends.\n \nUsed by the following ML models:\n- Automatic relevance tuning (default value: `1000`)\n- Event recommendation (default value: `1000`)"
          format: int32
          example: 500
        matchBasicExpression:
          type: boolean
          description: 'Whether all items recommended by the ML model should match the basic query expression (e.g., end-user input in the search box).


            Used by the following ML models:

            - Automatic relevance tuning (default value: `false`)'
        matchAdvancedExpression:
          type: boolean
          description: 'Whether all items recommended by the ML model should match the advanced query expression (e.g., facet selections).


            Used by the following ML models:

            - Automatic relevance tuning (default value: `true`)'
        intelligentTermDetection:
          type: boolean
          description: "Whether the ML model should use the Intelligent Term Detection (ITD) feature to refine queries by extracting relevant keywords from the large query expression and injecting those in the basic query expression.\n  \nUsed by the following ML models:\n- Automatic relevance tuning (default value: `false`)"
        intelligentTermDetectionPartialMatchThreshold:
          type: string
          description: 'An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression refined by the Intelligent Term Detection (ITD) feature.


            If specified, the `intelligentTermDetectionPartialMatchKeywords` value must either be:


            - a number between 1 and 10

            - a percentage value between 1% and 100% (e.g., `75%`)


            **Examples:**


            - `3`

            - `75%`


            **Notes:**


            - This parameter has no meaning unless the `intelligentTermDetection` parameter is set to `true`.


            Used by the following ML model:

            - Automatic relevance tuning (default value: `60%`)'
          example: 75%
          default: 60%
        intelligentTermDetectionPartialMatchKeywords:
          type: integer
          description: 'The minimum number of keywords that need to be present in an Intelligent Term Detection (ITD) response to convert it to a partial match expression.


            **Notes:**


            - This parameter has no meaning unless the `intelligentTermDetection` parameter is set to `true`.


            Used by the following ML model:

            - Automatic relevance tuning (default value: `1`)'
          format: int32
          example: 4
          default: 1
        condition:
          type: string
          description: The unique identifier of the condition that must be satisfied for a request to be processed by the ML model.
          example: 45a7892e-a63f-4c8e-8795-ab38c8c18d7e
        maxRecommendations:
          type: integer
          description: 'The maximum number of recommendations the ML model should return. This should be set to a relatively low value (typically well below 50), otherwise some of the recommended items may not actually be relevant. (Automatic relevance tuning default value: 5. Query suggest default value: 10)'
          format: int32
        cacheMaximumAge:
          type: string
          description: 'The maximum age of cached query results the ML model should accept, in the ISO - 8601 format only including the seconds and milliseconds part. **Default:** `PT1800S`.


            For each incoming query to be processed by the ML model, if a result set for an identical previously made query is available in cache and this result set is not older than the specified value, the ML model makes recommendations based on that cached query result set. Otherwise, the query is executed against the index.'
          example: PT300S
        enableWordCompletion:
          type: boolean
          description: 'Whether the ML model should attempt to complete the last word of the basic query expression and increase the ranking score of the resulting expression so that it is returned as the first completion suggestion.


            Used by the following ML models:

            - Query suggestions (default value: `true`)'
        description:
          type: string
          description: The ML model association description.
        exclusive:
          type: boolean
          description: 'Whether the Search API should only return items which were recommended by the ML model, even if other items matching the query were found in the index.


            Used by the following ML models:

            - Event recommendations (default value: `true`)

            - Product recommendations (default value: `true`)'
        customQueryParameters:
          type: object
          additionalProperties: true
          description: 'The additional parameters to send to Coveo ML.


            Among other things, this can be used to specify the [`strategy`](https://docs.coveo.com/en/p85e0425/) to use when querying a Product Recommendations model (for example, `{ "strategy": "frequentBought" }`. The valid `strategy` values are:


            - `cart`

            - `frequentBought`

            - `frequentViewed`

            - `popularBought`

            - `popularViewed`

            - `recentlyBought`

            - `recentlyViewed`

            - `user`'
        useAdvancedConfiguration:
          type: boolean
          description: '**Internal:** This property is exposed for internal use by the Coveo Cloud administration console.


            Whether the administration console should show the advanced editor for this association.


            **Note:** Properties not supported by the standard editor may not be preserved if managed via direct API calls or the advanced editor.


            **Default:** `false`'
        dynamicNavigationExperience:
          $ref: '#/components/schemas/DynamicNavigationExperienceConfiguration'
        contentIdKeys:
          type: array
          description: 'The names of the fields to use to uniquely identify items in the index.


            **Default:** `["permanentid","urihash"]`'
          items:
            type: string
        statementGroupId:
          type: string
          description: The unique identifier of the statement group.
          example: 679adb80-444e-11ea-b77f-2e728ce88125
        passageRetrieval:
          $ref: '#/components/schemas/PassageRetrievalConfiguration'
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            BadRequest:
              summary: 'Bad Request (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#400-bad_request)'
              value:
                statusCode: 400
                message: Invalid JSON format in request body.
            NoRegisteredEndpoint:
              summary: 'No Registered Endpoint (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#400-no_registered_endpoint)'
              value:
                statusCode: 400
                message: No registered endpoint found for this organization.
                errorCode: NO_REGISTERED_ENDPOINT
            QueryPipelineInterrupted:
              summary: 'Query Pipeline Interrupted (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#400-query_pipeline_interrupted)'
              value:
                statusCode: 400
                message: Failed to evaluate your query as some conditions in your pipeline took too much time.
                errorCode: QUERY_PIPELINE_INTERRUPTED
    TooManyRequests:
      description: 'Too Many Requests (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#429-too_many_requests)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            statusCode: 429
            message: Too many requests.
    ServiceUnavailable:
      description: 'Service Unavailable (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#5xx)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            ServiceUnavailable:
              summary: 'Server Unavailable (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#503-server_unavailable)'
              value:
                statusCode: 503
                message: The server is currently unavailable due to overload or index unavailability.
                errorCode: SERVER_UNAVAILABLE
            OrganizationPaused:
              summary: 'Organization Paused (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#503-organization_paused)'
              value:
                statusCode: 503
                message: The organization is paused due to inactivity.
                errorCode: ORGANIZATION_PAUSED
    AuthenticationTimeout:
      description: Authentication Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            statusCode: 419
            message: Authentication timeout.
    Forbidden:
      description: 'Forbidden (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#403-forbidden)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            statusCode: 403
            message: Access denied. API key does not have sufficient privileges.
            errorCode: FORBIDDEN
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            statusCode: 422
            message: Unprocessable entity.
    Unauthorized:
      description: 'Unauthorized (see: https://docs.coveo.com/en/1471/build-a-search-ui/troubleshoot-query-error-codes#401-unauthorized)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            statusCode: 401
            message: Invalid access token.
            errorCode: UNAUTHORIZED
  parameters:
    Page:
      name: page
      in: query
      description: The 0-based number of the page of results to get.
      schema:
        type: integer
        format: int32
        default: 0
        minimum: 0
    PerPage:
      name: perPage
      in: query
      description: The number of results to include per page.
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 200
        default: 20
    OrganizationIdQuery:
      name: organizationId
      in: query
      description: 'The unique identifier of the target Coveo Cloud organization.


        Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.'
      example: mycoveocloudv2organization
      schema:
        type: string
    PipelineIdPath:
      name: pipelineId
      in: path
      description: The unique identifier of the target query pipeline.
      required: true
      schema:
        type: string
  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