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: 'Th
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coveo/refs/heads/main/openapi/coveo-machine-learning-associations-api-openapi.yml