openapi: 3.0.1
info:
title: Coveo Activity Activities Listing 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: Listing Configurations
paths:
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/{configurationId}:
get:
tags:
- Listing Configurations
summary: Retrieves a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Shows a Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
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/listings/paramId_get
put:
tags:
- Listing Configurations
summary: Update a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Updates a Listing configuration in a [listing](https://docs.coveo.com/en/m1sf3187/).**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
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/listings/paramId_put
delete:
tags:
- Listing Configurations
summary: Deletes a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Deletes a Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:** `acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
format: uuid
responses:
'204':
description: No Content
x-pretty-name: delete
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/listings/paramId_delete
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/global:
get:
tags:
- Listing Configurations
summary: Retrieves the Global Listing Configuration for the Organization
description: 'Shows the global GlobalListing configuration. Does not accept pin rules. in an [organization](https://docs.coveo.com/en/185/).**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:
maxLength: 255
minLength: 1
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: getGlobal
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/listings/global_get
put:
tags:
- Listing Configurations
summary: Update the Global Listing Configuration for the Organization
description: 'Updates the global GlobalListing configuration. Does not accept pin rules. to be applied for the whole organization in a [listing](https://docs.coveo.com/en/m1sf3187/).**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/ListingConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: updateGlobal
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/listings/global_put
/rest/organizations/{organizationId}/commerce/v2/configurations/listings:
get:
tags:
- Listing Configurations
summary: Retrieves All Listing Configurations of an Organization. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Lists all the Listing configuration in an [organization](https://docs.coveo.com/en/185/).**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:
maxLength: 255
minLength: 1
type: string
- name: query
in: query
description: Filter on names when requesting listing configuration names & IDs. Will perform '*query*' match pattern.
required: false
schema:
type: string
example: Surf With Us Th
- name: page
in: query
description: The 0-based index number of the page of listing configurations to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of listing configurations to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelListingConfigurationModel'
x-pretty-name: getAll
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/listings_get
post:
tags:
- Listing Configurations
summary: Create a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Creates a Listing configuration in a [listing](https://docs.coveo.com/en/m1sf3187/).**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/ListingConfigurationModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
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/listings_post
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/url:
get:
tags:
- Listing Configurations
summary: Retrieves a Listing Configuration by Its Matching Url. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Shows a Listing configuration in an [organization](https://docs.coveo.com/en/185/).**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:
maxLength: 255
minLength: 1
type: string
- name: url
in: query
description: URL
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: getByUrl
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/listings/url_get
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/rules:
get:
tags:
- Listing Configurations
summary: Retrieves All Rules Related to Listings of an Organization. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Lists listing related rules in an [organization](https://docs.coveo.com/en/185/).**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
- name: configurationId
in: query
description: The unique identifier of the listing configuration.
required: false
schema:
type: string
format: uuid
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
- name: name
in: query
description: Filter on rule name when requesting rules.
required: false
schema:
type: string
example: Small name for a rule
- name: scope
in: query
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
required: false
schema:
type: string
enum:
- global
- specific
example: specific
- name: essential
in: query
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation. Returns all rules if not specified.
required: false
schema:
type: boolean
example: false
- name: language
in: query
description: An ISO 639-1 language code.
required: false
schema:
type: string
example: en
- name: country
in: query
description: An ISO 3166-1 alpha-2 country code.
required: false
schema:
type: string
example: US
- name: currency
in: query
description: An ISO 4217 currency code.
required: false
schema:
type: string
example: USD
- name: actions
in: query
description: 'Rule action type to return. One of: [boost, bury, pin, include, exclude, onlyShow]. Returns all if not specified.'
required: false
schema:
type: array
items:
type: string
enum:
- boost
- bury
- pin
- include
- exclude
example: '[boost]'
- name: sort
in: query
description: List of property.direction to sort by
required: false
schema:
type: array
items:
type: string
default:
- name.asc
example: name.asc
- name: scheduleFilter
in: query
description: The schedule filter to apply.
required: false
schema:
type: string
enum:
- live
- unscheduled
- expired
example: liveRules
- name: page
in: query
description: The 0-based index number of the page of rules to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of rules to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PaginatedRuleItems'
x-pretty-name: getRules
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/listings/rules_get
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/names:
get:
tags:
- Listing Configurations
summary: Retrieves All Listing Configurations Ids & Names of an Organization. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation) for more details.**Lists all ids and names of the Listing configuration in an [organization](https://docs.coveo.com/en/185/).**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:
maxLength: 255
minLength: 1
type: string
- name: query
in: query
description: Filter on names when requesting listing configuration names & IDs. Will perform '*query*' match pattern.
required: false
schema:
type: string
example: Surf With Us Th
- name: page
in: query
description: The 0-based index number of the page of listing configurations to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of listing configurations to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelListingConfigurationNameModel'
x-pretty-name: getAllNames
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/listings/names_get
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.
FieldValueModel:
required:
- type
type: object
properties:
type:
type: string
description: The value to apply the operator on.
example:
type: string
value: Blue
discriminator:
propertyName: type
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.
RulesModel:
type: object
properties:
rankingRules:
type: array
description: List of the ranking rules.
items:
$ref: '#/components/schemas/RankingRuleModel'
filterRules:
type: array
description: List of the filter rules.
items:
$ref: '#/components/schemas/FilterRuleModel'
pinRules:
type: array
description: List of the pin rules.
items:
$ref: '#/components/schemas/PinRuleModel'
description: Rules to apply at query time.
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
RankingRuleModel:
required:
- action
type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
value:
maximum: 1000
minimum: 0
type: integer
description: The scale at which the rule should be applied.
format: int32
example: 250
action:
type: string
description: Whether the rule is a boost or a bury.
example: boost
enum:
- boost
- bury
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
description: List of the ranking rules.
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.'
FilterRuleItem:
required:
- action
type: object
allOf:
- $ref: '#/components/schemas/RuleItemModel'
- type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
action:
type: string
description: Whether the rule is an include or an exclude.
example: include
enum:
- include
- exclude
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
MultipleStringValuesModel:
required:
- values
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
values:
minItems: 1
type: array
items:
maxLength: 255
minLength: 0
type: string
SeedRelativeValueModel:
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
RuleLocaleModel:
type: object
properties:
language:
type: string
description: An ISO 639-1 language code.
example: en
country:
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
type: string
description: An ISO 4217 currency code.
example: USD
description: The list of locales the synonym applies to. When empty, the synonym applies to all locales.
example:
- language: en
country: US
currency: USD
PaginatedRuleItems:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
oneOf:
- $ref: '#/components/schemas/FilterRuleItem'
- $ref: '#/components/schemas/PinRuleItem'
- $ref: '#/components/schemas/RankingRuleItem'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
DecimalValueModel:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
value:
type: number
format: double
SearchConditionModel:
required:
- operator
- values
type: object
properties:
operator:
type: string
description: The operator for the search condition.
enum:
- isExactly
- contains
values:
maxItems: 1
minItems: 0
type: array
description: Values that are used by the operator.
items:
type: string
description: Values that are used by the operator.
description: Search conditions associated to query-based rules on a search configuration.
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'
CommercePageModelListingConfigurationNameModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/ListingConfigurationNameModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
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.
QueryFilterModel:
required:
- fieldName
- operator
type: object
properties:
fieldName:
pattern: '[a-z][a-z0-9_]*'
type: string
description: The name of the field to apply the filter on.
example: name
operator:
type: string
description: The operator to apply on the field.
example: isExactly
enum:
- isExactly
- isExactlyNot
- contains
- doesNotContain
- isAnyOf
- isDefined
- isNotDefined
- isBetween
- isGreaterThan
- isGreaterThanOrEqualTo
- isLessThan
- isLessThanOrEqualTo
value:
oneOf:
- $ref: '#/components/schemas/DecimalValueModel'
- $ref: '#/components/schemas/HierarchicMultiValueModel'
- $ref: '#/components/schemas/InclusiveRangeModel'
- $ref: '#/components/schemas/MultipleStringValuesModel'
- $ref: '#/components/schemas/SeedRelativeValueModel'
- $ref: '#/components/schemas/StringValueModel'
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
SortByRelevanceModel:
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortModel'
PinRuleModel:
type: object
properties:
rankByPermanentId:
type: array
description: A map of product permanent IDs to their desired rank.
example:
'123456789': 1
'987654321': 2
items:
type: object
additionalProperties:
type: integer
format: int32
action:
type: string
description: Whether the rule is a pin.
example: pin
enum:
- pin
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
description: List of the pin rules.
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.
InclusiveRangeModel:
required:
- range
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
range:
$ref: '#/components/schemas/RangeModel'
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.
RangeModel:
type: object
properties:
from:
type: number
format: double
to:
type: number
format: double
MatchingConfigurationModel:
required:
- url
type: object
properties:
url:
maxLength: 1024
minLength: 1
type: string
description: URL associated to a listing configuration used for pattern matching.
description: Possible patterns matching values associated to a listing configuration.
example:
- url: https://sports.barca.group/plp/clothing/pants
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.
CommercePageModelListingConfigurationModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/ListingConfigurationModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
ListingConfigurationModel:
required:
- name
- patterns
- rules
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the listing configuration.
format: uuid
readOnly: true
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the listing configuration.
example: ACME Corp Summer Trends
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
patterns:
minItems: 1
type: array
description: Possible patterns matching values associated to a listing configuration.
example:
- url: https://sports.barca.group/plp/clothing/pants
items:
$ref: '#/components/schemas/MatchingConfigurationModel'
queryConfiguration:
$ref: '#/components/schemas/QueryConfigurationLegacyModel'
rules:
$ref: '#/components/schemas/RulesModel'
facetCollectionConfigurationId:
type: string
description: The unique identifier of the [facet collection configuration](https://docs.coveo.com/en/p5890502/glossary/facet-collection).Can only be modified via /facetCollection endpoint
format: uuid
readOnly: true
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
scope:
type: string
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
example: specific
enum:
- global
- specific
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.
ListingConfigurationNameModel:
required:
- name
- url
type: object
properties:
id:
type: string
description: The unique identifier of the listing configuration.
format: uuid
readOnly: true
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the listing configuration.
example: ACME Corp Summer Trends
url:
maxLength: 1024
minLength: 1
type: string
description: URL associated to a listing configuration used for pattern matching.
description: The retrieved page of items.
QueryConfigurationLegacyModel:
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'
filterFieldRange:
type: integer
description: 'Default: `5`
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
productGrouping:
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: Query configuration.
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.
PinRuleItem:
type: object
allOf:
- $ref: '#/components/schemas/RuleItemModel'
- type: object
properties:
rankByPermanentId:
type: array
description: A map of product permanent IDs to their desired rank.
example:
'123456789': 1
'987654321': 2
items:
type: object
additionalProperties:
type: integer
format: int32
action:
type: string
description: Whether the rule is a pin.
example: pin
enum:
- pin
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
HierarchicMultiValueModel:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
value:
maxLength: 255
minLength: 0
type: string
FilterRuleModel:
required:
- action
type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
action:
type: string
description: Whether the rule is an include or an exclude.
example: include
enum:
- include
- exclude
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
description: List of the filter rules.
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
RuleItemModel:
type: object
properties:
trackingId:
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
configurationId:
type: string
description: The unique identifier of the configuration (search or listing) this rule belongs to.
format: uuid
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
scope:
type: string
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
example: specific
enum:
- global
- specific
conditions:
type: array
description: Conditions under which the rule is applied.
example:
- operator: isExactly
values:
- mens shoes
items:
$ref: '#/components/schemas/SearchConditionModel'
configurationName:
type: string
description: Name of the configuration this rule is applied to.
example: Surf With Us This Year
configurationType:
type: string
description: Type of configuration this rule is applied to.
example: listing
enum:
- listing
- search
scheduleStartDate:
type: string
description: The start date of the Schedule.
format: date-time
scheduleEndDate:
type: string
description: The end date of the Schedule.
format: date-time
type:
type: string
description: Type of the rule returned.
example: '[filter, pin, ranking]'
enum:
- filter
- pin
- ranking
description: The retrieved page of items.
discriminator:
propertyName: type
RankingRuleItem:
required:
- action
type: object
allOf:
- $ref: '#/components/schemas/RuleItemModel'
- type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
value:
maximum: 1000
minimum: 0
type: integer
description: The scale at which the rule should be applied.
format: int32
example: 250
action:
type: string
description: Whether the rule is a boost or a bury.
example: boost
enum:
- boost
- bury
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
StringValueModel:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
value:
maxLength: 255
minLength: 0
type: string
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