openapi: 3.0.1
info:
title: Coveo Activity Activities Query Configurations 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: Query Configurations
paths:
/rest/organizations/{organizationId}/commerce/v2/configurations/query:
get:
tags:
- Query Configurations
summary: Get Query Configuration for a Solution
description: 'Retrieves the query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters within the query configuration model are supported.**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: solutionType
in: query
description: The solution type for the rule. It can be either 'listing' or 'search' or 'recommendations'.
required: true
schema:
type: string
enum:
- listing
- search
- recommendation
- name: targets
in: query
description: List of target identifiers e.g. listing page name, slot ID
required: false
schema:
maxItems: 1
minItems: 1
type: array
items:
type: string
example:
- Surf With Us This Year
- name: isGlobal
in: query
description: Whether the query configuration is globally applied.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryConfigurationModel'
x-pretty-name: get
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_get
put:
tags:
- Query Configurations
summary: Update Query Configuration for a Solution
description: 'Updates a query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters within the query configuration model are supported.**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConfigurationRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryConfigurationModel'
x-pretty-name: update
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_put
post:
tags:
- Query Configurations
summary: Create Query Configuration for a Solution
description: 'Creates a query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters within the query configuration model are supported**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConfigurationRequestModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryConfigurationModel'
x-pretty-name: create
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_post
delete:
tags:
- Query Configurations
summary: Delete the Query Configuration of a Solution
description: 'Deletes a query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters within the query configuration model are supported.**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: solutionType
in: query
description: The solution type for the rule. It can be either 'listing' or 'search' or 'recommendations'.
required: true
schema:
type: string
enum:
- listing
- search
- recommendation
- name: targets
in: query
description: List of target identifiers e.g. listing page name, slot ID
required: false
schema:
maxItems: 1
minItems: 1
type: array
items:
type: string
example:
- Surf With Us This Year
- name: isGlobal
in: query
description: Whether the query configuration is globally applied.
required: false
schema:
type: boolean
default: false
responses:
'204':
description: No Content
x-pretty-name: delete
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_delete
components:
schemas:
NumericalRangeFacetRequestModel:
required:
- displayNames
- field
type: object
description: Numerical range facet.
example:
facetId: ec_price
field: ec_price
displayNames:
- value: Price
language: en
- value: Prix
language: fr
values:
- state: idle
preventAutoSelect: true
start: '0'
end: '999'
endInclusive: 'true'
- state: selected
preventAutoSelect: true
start: '1000'
end: '2000'
endInclusive: 'false'
- state: selected
preventAutoSelect: true
start: '2001'
end: '3000'
endInclusive: 'false'
numberOfValues: 3
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: numericalRange
generateAutomaticRanges: true
rangeAlgorithm: equiprobable
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/NumericalRangeFacetRequestValueModel'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field must be a facet field with the ''Use cache for nested queries'' options enabled.'
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
interval:
type: string
description: Determines the range interval type. Default is `continuous`.
default: continuous
enum:
- continuous
- discrete
- even
- equiprobable
domain:
$ref: '#/components/schemas/RangeDomain'
freezeCurrentValues:
type: boolean
description: Whether to freeze the current list of facet values. Setting this to true keeps the facet from moving around while the end-user interacts with it on the storefront.
rangeAlgorithm:
type: string
description: Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.
enum:
- equiprobable
- even
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
DateRangeFacetRequestModel:
required:
- displayNames
- field
type: object
description: Date range facet.
example:
facetId: year
field: year
displayNames:
- value: Year
language: en
- value: Année
language: fr
values:
- state: idle
preventAutoSelect: false
start: 2023/10/01@00:00:00
end: 2023/10/31@23:59:59
endInclusive: true
- state: idle
preventAutoSelect: true
start: 2023/11/01@00:00:00
end: 2023/11/30@23:59:59
endInclusive: false
- state: selected
preventAutoSelect: true
start: 2023/12/01@00:00:00
end: 2023/12/31@23:59:59
endInclusive: true
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: dateRange
generateAutomaticRanges: true
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/DateRangeFacetRequestValueModel'
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
freezeCurrentValues:
type: boolean
description: Whether to freeze the current list of facet values. Setting this to true keeps the facet from moving around while the end-user interacts with it on the storefront.
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field must be a facet field with the ''Use cache for nested queries'' options enabled.'
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
QueryConfigurationModel:
type: object
properties:
additionalFields:
uniqueItems: true
type: array
description: To retrieve [additional fields](https://docs.coveo.com/en/n73f0502#create-additional-commerce-fields) you have created, that aren’t part of the [standard commerce fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields), specify them here. These fields appear in the `additionalFields` object in the response.
example:
- color
- shirtsize
items:
type: string
facets:
$ref: '#/components/schemas/FacetRequestModel'
perPage:
maximum: 100
minimum: 0
type: integer
description: The number of results to include per page.
Note: The specified value applies only to parent items, not their grouped children. Query performance may be affected when returned items include many grouped products.
format: int32
example: 20
sorts:
type: array
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
items:
oneOf:
- $ref: '#/components/schemas/SortByFieldsModel'
- $ref: '#/components/schemas/SortByRelevanceModel'
numberOfChildren:
type: integer
description: Equivalent to `filterFieldRange` in the Search API. The maximum number of items to include in the childResults array of a folded query result (see SearchAPI's doc for more details).
format: int32
grouping:
$ref: '#/components/schemas/QueryParamGroupingOverridesConfigModel'
description: Query configuration.
AbstractSortModel:
type: object
properties:
sortCriteria:
type: string
description: The criterion to use for sorting the results.
enum:
- relevance
- fields
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
discriminator:
propertyName: sortCriteria
FacetRequestModel:
type: object
properties:
enableIndexFacetOrdering:
type: boolean
description: 'Default: `true`
Whether to take into account the scores generated by the index when reordering facets.
Note: Setting this to `false` implies that only the scores generated by a Coveo ML DNE model will be taken into account when automatically reordering facets. To completely disable automatic facet reordering, set `freezeFacetOrder` to `true` instead.'
freezeFacetOrder:
type: boolean
description: 'Default: `false`
Whether facets should be returned in the same order in which they were requested.
Note: Setting this to `true` completely disables automatic facet reordering. To allow automatic facet reordering, but only take into account the scores generated by a Coveo ML DNE model, set `enableIndexFacetOrdering` to `false` instead.'
facets:
type: array
description: The facet operations to perform on the listing query.
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetRequestModel'
- $ref: '#/components/schemas/HierarchicalFacetRequestModel'
- $ref: '#/components/schemas/NumericalRangeFacetRequestModel'
- $ref: '#/components/schemas/RegularFacetRequestModel'
description: 'DEPRECATED ON 2026-08-31: The facet request configuration. See https://docs.coveo.com/en/q3cc0299/deprecations/legacy-commerce-api-facet-management-deprecation for more details on the deprecation.'
SortByFieldsModel:
required:
- fields
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortModel'
- type: object
properties:
fields:
minItems: 1
type: array
description: Defines the fields and, optionally, their sort order.
items:
$ref: '#/components/schemas/SortByFieldModel'
DateRangeFacetRequestValueModel:
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.
BasePath:
required:
- language
- value
type: object
properties:
value:
minItems: 1
type: array
description: The base path shared by all values for the facet.
items:
type: string
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
description: List of localized Base path shared by all values for the facet.
SortByRelevanceModel:
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortModel'
RangeDomain:
required:
- max
- min
type: object
properties:
min:
minimum: 0
type: integer
format: int32
max:
maximum: 1000000
type: integer
format: int32
increment:
maximum: 1000000
minimum: 0
type: integer
format: int32
description: Limits the range values to the specified domain.
NumericalRangeFacetRequestValueModel:
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.
description: The values displayed by the facet in the search interface at the moment of the request.
DisplayName:
required:
- language
- value
type: object
properties:
value:
minLength: 1
type: string
description: DEPRECATED - The display name of a field.
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
description: The display names of a field to sort by associated with its language.
SortByFieldModel:
required:
- displayNames
- field
type: object
properties:
field:
minLength: 1
pattern: ^([a-z][a-z0-9_]{0,254})$
type: string
description: The name of a field to sort by.
direction:
type: string
description: 'Sort order:
Default: `ascending`
- `asc` - Ascending, from A to Z
- `desc` - Descending, from Z to A
'
enum:
- asc
- desc
displayNames:
minItems: 1
uniqueItems: true
type: array
description: The display names of a field to sort by associated with its language.
items:
$ref: '#/components/schemas/DisplayName'
description: Defines the fields and, optionally, their sort order.
RegularFacetRequestModel:
required:
- displayNames
- field
type: object
description: Regular (single string value) facet.
example:
facetId: ec_brand
field: ec_brand
displayNames:
- value: Brand
language: en
- value: Marque
language: fr
values:
- state: selected
preventAutoSelect: false
value: Aqua Sports
- state: idle
preventAutoSelect: false
value: Aqua Marina
- state: idle
preventAutoSelect: false
value: HO Sports
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: regular
customOrder:
- string
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/RegularFacetRequestValueModel'
customOrder:
type: array
description: A custom sort order for the facet values.
items:
type: string
freezeCurrentValues:
type: boolean
description: Whether to freeze the current list of facet values. Setting this to true keeps the facet from moving around while the end-user interacts with it on the storefront.
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field must be a facet field with the ''Use cache for nested queries'' options enabled.'
resultsMustMatch:
type: string
description: Specifies how a result must match the selected values.
default: atLeastOneValue
enum:
- atLeastOneValue
- allValues
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
QueryConfigurationRequestModel:
required:
- configurationModel
- solutionType
- trackingId
type: object
properties:
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
solutionType:
type: string
description: The solution type for the rule. It can be either 'listing' or 'search' or 'recommendations'.
enum:
- listing
- search
- recommendation
targets:
maxItems: 1
minItems: 1
type: array
description: List of target identifiers e.g. listing page name, slot ID
example:
- Surf With Us This Year
items:
type: string
description: List of target identifiers e.g. listing page name, slot ID
example: '["Surf With Us This Year"]'
isGlobal:
type: boolean
description: Whether the query configuration is globally applied.
default: false
configurationModel:
$ref: '#/components/schemas/QueryConfigurationModel'
description: Request for editing query configurations.
HierarchicalFacetRequestModel:
required:
- displayNames
- field
type: object
description: Hierarchical (tree-like) facet.
example:
facetId: ec_category
field: ec_category
displayNames:
- value: Category
language: en
- value: Catégorie
language: fr
values:
- state: selected
preventAutoSelect: true
value: Canoes & Kayaks
children:
- state: selected
preventAutoSelect: true
value: Kayaks
children:
- state: selected
preventAutoSelect: true
value: Folding Kayaks
- state: idle
preventAutoSelect: true
value: Sea Kayaks
- state: selected
preventAutoSelect: false
value: Canoes
numberOfValues: 5
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: hierarchical
delimitingCharacter: '|'
basePaths:
value:
- Boats
language: en
filterByBasePath: true
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/HierarchicalFacetRequestValueModel'
delimitingCharacter:
type: string
description: The character to use to split field values into a hierarchical sequence.
basePaths:
uniqueItems: true
type: array
description: List of localized Base path shared by all values for the facet.
items:
$ref: '#/components/schemas/BasePath'
filterByBasePath:
type: boolean
description: Whether to use basePath as a filter for the results.
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field must be a facet field with the ''Use cache for nested queries'' options enabled.'
retrieveCount:
type: integer
description: The maximum number of children to retrieve for this hierarchical facet values.
format: int32
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
HierarchicalFacetRequestValueModel:
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/HierarchicalFacetRequestValueModel'
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.
QueryParamGroupingOverridesConfigModel:
required:
- type
type: object
properties:
type:
type: string
description: The product grouping. Determines if pin rules should consider results to be grouped on the query pipeline, or not.
enum:
- none
- query_pipeline
description: The product grouping. Determines if pin rules should consider results to be grouped on the query pipeline, or not.
AbstractFacetRequestModelObject:
required:
- displayNames
- field
type: object
properties:
facetId:
type: string
description: The facet id. Common practice is to use the facet field name, unless there are multiple facet configurations for the same field.
example: ec_brand
field:
minLength: 1
pattern: ^([a-z][a-z0-9_]{0,254})$
type: string
description: The facet field name.
example: ec_brand
displayNames:
minItems: 1
uniqueItems: true
type: array
description: The facet display name with its associated language.
items:
$ref: '#/components/schemas/DisplayName'
values:
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: integer
description: The maximum number of facet values to fetch.
format: int32
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 listing query.
discriminator:
propertyName: type
RegularFacetRequestValueModel:
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: The facet value name.
description: The values displayed by the facet in the search interface at the moment of the request.
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