Search API (v1)

Search V3

Send search request

See Performing a Query.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string (AQ)

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string (CQ)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

disableQuerySyntax
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string (DQ)

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean
Default: false

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean
Default: false

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean
Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean
Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean
Default: true

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>
Default: 200

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)
Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>
Default: 5

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>
Default: 0

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

object

Generate facets based on the most relevant fields in the index.

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean
Default: false

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string (LQ)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer <int32>
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

lqPartialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>
Default: 3

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>
Default: 1

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean
Default: false

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0
Default: 10

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean
Default: false

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string (Q)

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

object

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

  • Attempt to correct your query if it doesn't return enough results.
  • If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

  • The original query
  • The corrected query

Otherwise, it will return:

  • A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean
Default: false

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string
Default: "Relevancy"

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean
Default: false

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>
Default: 0

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)
visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean
Default: false

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Request samples

Content type
application/json
{
  • "aq": "@year==2017",
  • "categoryFacets": [
    ],
  • "childField": "@foldingparent",
  • "commerce": {
    },
  • "cq": "@documenttype==forumpost",
  • "dictionaryFieldContext": {
    },
  • "disableQuerySyntax": false,
  • "dq": "@permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd",
  • "enableCollaborativeRating": false,
  • "enableDidYouMean": true,
  • "enableDuplicateFiltering": true,
  • "enableMLDidYouMean": true,
  • "enableQuerySyntax": true,
  • "excerptLength": 250,
  • "facetOptions": {
    },
  • "facets": [
    ],
  • "fieldsToExclude": [
    ],
  • "fieldsToInclude": [
    ],
  • "filterField": "@foldingcollection",
  • "filterFieldRange": 8,
  • "firstResult": 2,
  • "generateAutomaticFacets": {
    },
  • "groupBy": [
    ],
  • "lowercaseOperators": false,
  • "lq": "I am looking for an enterprise-class native cloud SaaS/PaaS solution that provides a unified and secure way to search for contextually relevant content across multiple enterprise systems.",
  • "lqPartialMatchKeywords": 4,
  • "lqPartialMatchMaxKeywords": 20,
  • "lqPartialMatchThreshold": "75%",
  • "mlDidYouMeanMaxCandidates": 5,
  • "mlDidYouMeanMinScore": 0.8,
  • "mlDidYouMeanUseFacetCount": true,
  • "numberOfResults": 5,
  • "parentField": "@foldingchild",
  • "partialMatch": true,
  • "partialMatchKeywords": 4,
  • "partialMatchThreshold": "75%",
  • "q": "Coveo \"Cloud V2\" platform",
  • "queryCorrection": {
    },
  • "queryFunctions": [
    ],
  • "questionMark": true,
  • "rankingFunctions": [
    ],
  • "retrieveFirstSentences": true,
  • "sortCriteria": "DateDescending",
  • "sortField": "string",
  • "staticQuery": true,
  • "summaryLength": 0,
  • "userActions": {
    },
  • "wildcards": true,
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
{
  • "apiVersion": 2,
  • "categoryFacets": [
    ],
  • "duration": 1235,
  • "errors": [
    ],
  • "exception": {
    },
  • "extendedResults": {
    },
  • "facets": [
    ],
  • "generateAutomaticFacets": {
    },
  • "groupByResults": [
    ],
  • "index": "mycoveocloudv2organizationid-cqjd206sta1xb9qyxfhhnsu294-Indexer-2-9rbfxhp1n07cth80ckzeh3zotc",
  • "indexDuration": 1175,
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "isFallbackToAdmin": true,
  • "phrasesToHighlight": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "queryCorrection": {
    },
  • "queryCorrections": [ ],
  • "questionAnswer": {
    },
  • "refinedKeywords": [
    ],
  • "requestDuration": 1181,
  • "results": [
    ],
  • "searchUid": "a0e4773c-39c3-423c-90cd-c03a640ecde5",
  • "splitTestRun": "CustomerQueryPipeline-mirror-1725560351",
  • "suggestedFacets": [
    ],
  • "termsToHighlight": {
    },
  • "totalCount": 250,
  • "totalCountFiltered": 245,
  • "triggers": [
    ],
  • "warnings": [
    ]
}

Get item data stream

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
contentType
string

The MIME type of the data stream to request.

Default: application/binary

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

dataStream
required
string

The name of the data stream to request.

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Get item in JSON format

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Response samples

Content type
application/json
{
  • "ClickUri": "string",
  • "Excerpt": "string",
  • "FirstSentences": "string",
  • "PrintableUri": "string",
  • "Title": "string",
  • "UniqueId": "string",
  • "Uri": "string",
  • "absentTerms": [
    ],
  • "childResults": [
    ],
  • "excerpt": "... the new Coveo Cloud V2 and Coveo Cloud V1 ... the main differences between the two Coveo Cloud versions ...",
  • "excerptHighlights": [
    ],
  • "firstSentences": "Hello, I know Coveo currently hosts organizations in two independent cloud platforms, the new Coveo Cloud V2 and Coveo Cloud V1, the original Coveo offering in the cloud. I would like to learn the main differences between the two Coveo Cloud versions ...",
  • "firstSentencesHighlights": [
    ],
  • "flags": "HasHtmlVersion;HasMobileHtmlVersion",
  • "hasHtmlVersion": true,
  • "hasMobileHtmlVersion": true,
  • "isRecommendation": false,
  • "isTopResult": false,
  • "isUserActionView": false,
  • "parentResult": { },
  • "percentScore": 90.73539,
  • "printableUriHighlights": [
    ],
  • "rankingInfo": "Document weights:\nTitle: 0; Quality: 180; Date: 596; Adjacency: 0; Source: 500; Custom: 350; Collaborative rating: 0; QRE: 0; Ranking functions: 0;\n\nTotal weight: 1626",
  • "rankingModifier": "TopResult",
  • "rating": 3,
  • "raw": {
    },
  • "score": 1626,
  • "summary": "string",
  • "summaryHighlights": [
    ],
  • "title": "Differences between Coveo Cloud V2 and V1",
  • "titleHighlights": [
    ],
  • "totalNumberOfChildResults": 0,
  • "uniqueId": "84.72597$https://example.com/Root:0/Topic:898/Post:2",
}

Send facet search request

Executes a facet search request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
field
required
string

The name of the field against which to execute the facet search request.

basePath
Array of strings

The shared base path for all values in the facet to search against.

If a basePath is specified, the search request will be executed against hierarchical values that begin with that base path only (i.e., other hierarchical values will be filtered out).

object

A dictionary that maps index field values to facet value display names.

Note:

When specifying display captions for hierarchical facet values, you can use full values (e.g., all;electronics;laptops), and/or for "leaf" values (e.g., laptops) as keys. If both are provided, the full value takes priority.

Examples:

  • Specific (i.e., scalar) facet values: {\"#FF8000\": \"Orange\", \"#8000FF\": \"Purple\"}
  • Hierarchical facet values:** `{"all;electronics;laptops": "Laptops", "smartphones": "Smart Phones"} "
delimitingCharacter
string

The character to use to split field values into a hierarchical sequence.

Example:

For a multi-value field containing the following values:

c; c>folder2; c>folder2>folder3;

The delimiting character is >.

For a hierarchical field containing the following values: c;folder2;folder3;

The delimiting character is ;.

Default: ;

filterFacetCount
boolean

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: false

ignorePaths
Array of strings[ items ]

A list of paths to filter out from the hierarchical facet search results.

numberOfValues
integer <int32>
Default: 10

The maximum number of values to fetch.

**Default: 10

query
string

The string to match.

Note: Typically, this should be set to the text entered by the end-user in the facet search box, to which one or more wildcard characters (*) may be added.

object (RestQueryParameters)
type
string

The kind of facet against which the search request is being made.

Allowed values:

  • specific
  • hierarchical

Default: specific

Responses

Request samples

Content type
application/json
Example
{
  • "basePath": [
    ],
  • "captions": {
    },
  • "delimitingCharacter": "string",
  • "field": "color",
  • "filterFacetCount": [
    ],
  • "ignorePaths": [
    ],
  • "numberOfValues": 10,
  • "query": "*oran*",
  • "searchContext": {
    },
  • "type": "hierarchical"
}

Response samples

Content type
application/json
{
  • "moreValuesAvailable": true,
  • "values": [
    ]
}

List all fields

Gets all fields in the target Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Response samples

Content type
application/json
{
  • "fields": [
    ]
}

Find fields from results of a query expression

Find fields name from results matching the q expression.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"VIEW_ALL_CONTENT","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json

The query to get the fields from.

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

q
string
Default: ""

The basic query expression, typically the keywords entered by the end user in a query box.

Responses

Request samples

Content type
application/json
{
  • "dictionaryFieldContext": {
    },
  • "q": "Coveo \"Cloud V2\" platform"
}

Response samples

Content type
application/json
{
  • "fields": [
    ]
}

Get HTML item preview

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
enableNavigation
boolean
findNext
integer <int32>
findPrevious
integer <int32>
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32>
requestedOutputSize
integer <int32>

The approximate number of bytes to request in the HTML response. Default: 0, meaning that the entire HTML document is requested.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string (AQ)

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string (CQ)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

disableQuerySyntax
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string (DQ)

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean
Default: false

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean
Default: false

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean
Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean
Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean
Default: true

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>
Default: 200

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)
Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>
Default: 5

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>
Default: 0

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

object

Generate facets based on the most relevant fields in the index.

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean
Default: false

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string (LQ)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer <int32>
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

lqPartialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>
Default: 3

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>
Default: 1

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean
Default: false

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0
Default: 10

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean
Default: false

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string (Q)

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

object

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

  • Attempt to correct your query if it doesn't return enough results.
  • If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

  • The original query
  • The corrected query

Otherwise, it will return:

  • A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean
Default: false

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string
Default: "Relevancy"

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean
Default: false

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>
Default: 0

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)
visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean
Default: false

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Request samples

Content type
application/json
{
  • "aq": "@year==2017",
  • "categoryFacets": [
    ],
  • "childField": "@foldingparent",
  • "commerce": {
    },
  • "cq": "@documenttype==forumpost",
  • "dictionaryFieldContext": {
    },
  • "disableQuerySyntax": false,
  • "dq": "@permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd",
  • "enableCollaborativeRating": false,
  • "enableDidYouMean": true,
  • "enableDuplicateFiltering": true,
  • "enableMLDidYouMean": true,
  • "enableQuerySyntax": true,
  • "excerptLength": 250,
  • "facetOptions": {
    },
  • "facets": [
    ],
  • "fieldsToExclude": [
    ],
  • "fieldsToInclude": [
    ],
  • "filterField": "@foldingcollection",
  • "filterFieldRange": 8,
  • "firstResult": 2,
  • "generateAutomaticFacets": {
    },
  • "groupBy": [
    ],
  • "lowercaseOperators": false,
  • "lq": "I am looking for an enterprise-class native cloud SaaS/PaaS solution that provides a unified and secure way to search for contextually relevant content across multiple enterprise systems.",
  • "lqPartialMatchKeywords": 4,
  • "lqPartialMatchMaxKeywords": 20,
  • "lqPartialMatchThreshold": "75%",
  • "mlDidYouMeanMaxCandidates": 5,
  • "mlDidYouMeanMinScore": 0.8,
  • "mlDidYouMeanUseFacetCount": true,
  • "numberOfResults": 5,
  • "parentField": "@foldingchild",
  • "partialMatch": true,
  • "partialMatchKeywords": 4,
  • "partialMatchThreshold": "75%",
  • "q": "Coveo \"Cloud V2\" platform",
  • "queryCorrection": {
    },
  • "queryFunctions": [
    ],
  • "questionMark": true,
  • "rankingFunctions": [
    ],
  • "retrieveFirstSentences": true,
  • "sortCriteria": "DateDescending",
  • "sortField": "string",
  • "staticQuery": true,
  • "summaryLength": 0,
  • "userActions": {
    },
  • "wildcards": true,
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Log in to authentication provider

Directs the browser to URI of the target Search API authentication provider, and back to the origin search page once the authentication process is complete. This authentication provider must be properly configured in the Coveo Cloud organization.

Privilege(s) required

Authorizations:
oauth2
path Parameters
provider
required
string
Example: My SharePoint Server

The name of the Search API authentication provider to log in to.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Plan search execution

See Performing a Query.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string (AQ)

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string (CQ)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

disableQuerySyntax
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string (DQ)

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean
Default: false

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean
Default: false

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean
Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean
Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean
Default: true

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>
Default: 200

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)
Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>
Default: 5

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>
Default: 0

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

object

Generate facets based on the most relevant fields in the index.

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean
Default: false

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string (LQ)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer <int32>
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

lqPartialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>
Default: 3

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>
Default: 1

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean
Default: false

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0
Default: 10

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean
Default: false

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string (Q)

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

object

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

  • Attempt to correct your query if it doesn't return enough results.
  • If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

  • The original query
  • The corrected query

Otherwise, it will return:

  • A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean
Default: false

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string
Default: "Relevancy"

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean
Default: false

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>
Default: 0

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)
visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean
Default: false

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Request samples

Content type
application/json
{
  • "aq": "@year==2017",
  • "categoryFacets": [
    ],
  • "childField": "@foldingparent",
  • "commerce": {
    },
  • "cq": "@documenttype==forumpost",
  • "dictionaryFieldContext": {
    },
  • "disableQuerySyntax": false,
  • "dq": "@permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd",
  • "enableCollaborativeRating": false,
  • "enableDidYouMean": true,
  • "enableDuplicateFiltering": true,
  • "enableMLDidYouMean": true,
  • "enableQuerySyntax": true,
  • "excerptLength": 250,
  • "facetOptions": {
    },
  • "facets": [
    ],
  • "fieldsToExclude": [
    ],
  • "fieldsToInclude": [
    ],
  • "filterField": "@foldingcollection",
  • "filterFieldRange": 8,
  • "firstResult": 2,
  • "generateAutomaticFacets": {
    },
  • "groupBy": [
    ],
  • "lowercaseOperators": false,
  • "lq": "I am looking for an enterprise-class native cloud SaaS/PaaS solution that provides a unified and secure way to search for contextually relevant content across multiple enterprise systems.",
  • "lqPartialMatchKeywords": 4,
  • "lqPartialMatchMaxKeywords": 20,
  • "lqPartialMatchThreshold": "75%",
  • "mlDidYouMeanMaxCandidates": 5,
  • "mlDidYouMeanMinScore": 0.8,
  • "mlDidYouMeanUseFacetCount": true,
  • "numberOfResults": 5,
  • "parentField": "@foldingchild",
  • "partialMatch": true,
  • "partialMatchKeywords": 4,
  • "partialMatchThreshold": "75%",
  • "q": "Coveo \"Cloud V2\" platform",
  • "queryCorrection": {
    },
  • "queryFunctions": [
    ],
  • "questionMark": true,
  • "rankingFunctions": [
    ],
  • "retrieveFirstSentences": true,
  • "sortCriteria": "DateDescending",
  • "sortField": "string",
  • "staticQuery": true,
  • "summaryLength": 0,
  • "userActions": {
    },
  • "wildcards": true,
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "parsedInput": {
    },
  • "preprocessingOutput": {
    }
}

Request query suggestions

See Getting Query Suggestions.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
autoCompleter
string
Deprecated

This parameter is exposed for backward compatibility reasons.

object (RestCommerceParameters)
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

count
integer <int32>

The desired number of query suggestions.

debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

enableWordCompletion
boolean

Whether to attempt to complete the last word of the current basic query expression (see the q parameter) and boost the ranking score of the resulting expression so that it is returned as the first query suggestion.

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string

The basic query expression, typically the keywords entered by the end user in a query box.

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Request samples

Content type
application/json
{
  • "autoCompleter": "string",
  • "count": 0,
  • "enableWordCompletion": true,
  • "q": "Coveo \"Cloud V2\" platform",
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "commerce": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "completions": [
    ],
  • "responseId": "e1a4c9dd-71d2-4e68-9589-11bc3e640da0"
}

Get item in text format

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Create search token

Creates a temporary JSON web token which can be used to impersonate one or several security identities when authenticating a query (see Search Token Authentication).

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"IMPERSONATE_SEARCH_API","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The search token information.

required
Array of objects (RestUserId)

The security identities to impersonate when authenticating a query with this search token.

canSeeUserProfileOf
Array of strings

The username and/or visitorId values whose corresponding usage analytics-recorded user profiles can be accessed using the search token.

Note: This property is meant to be used when generating search tokens for users requiring contextual information about other users to improve search relevance (e.g., support agents using an insight panel).

object (CommerceParameters)
dictionaryFieldContext
object

The dictionary field context to enforce when authenticating a query with this search token. This value will override the dictionaryFieldContext parameter of the query itself.

A dictionary field context is a key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

For example, suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } when creating a search token means that, for any query made with that search token, any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This cannot be used at the same time as allowedDictionaryFieldKeys.

filter
string

The filter query expression to apply when authenticating a query with this search token.

This expression will be merged with the constant part of the query expression (cq) using an AND operator.

The filter can also be used in query pipeline condition statements (e.g., when $constantQuery contains \"@source==KnowledgeBase\").

licenseDefinitionKey
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

pipeline
string

The name of the query pipeline to use when authenticating a query with this search token.

This query pipeline will take precedence over the possible output of all other query pipeline routing mechanisms when using this search token (see Query Pipeline Routing Mechanisms and Rules).

salesforceCommunityUrl
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

salesforceFallbackToAdmin
boolean

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

salesforceOrganizationId
string

Internal: The ID of Salesforce organization, used to differentiate Salesforce organizations linked to the same Coveo organization.

salesforceUser
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

scope
integer <int32>
Deprecated

This property is exposed for backward compatibility reasons only.

searchHub
string

The name of the search hub to enforce when authenticating a query with this search token.

This value will override the searchhub parameter of the query itself, and will be passed as the originLevel1 property value when logging usage analytics search events.

The search hub can also be used in query pipeline condition statements (e.g., when $searchhub is \"CommunityHub\").

superUserToken
string
Deprecated

This property is exposed for backward compatibility reasons only.

userDisplayName
string

The userDisplayName to pass when logging usage analytics search events.

This information is leveraged in the Analytics section of the Coveo Cloud administration console.

userGroups
Array of strings

The userGroups to pass when logging usage analytics search events.

This information is leveraged in the Analytics section of the Coveo Cloud administration console.

User groups can be also be used in query pipeline condition statements (e.g., when $groups contains \"Employees\").

usertype
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

validFor
integer <int32>
Default: 86400000

The number of milliseconds the search token will remain valid for once it has been created.

Minimum value: 900000 (i.e., 15 minutes)

Maximum/default: 86400000 (i.e., 24 hours)

Responses

Request samples

Content type
application/json
{
  • "canSeeUserProfileOf": [
    ],
  • "commerce": {
    },
  • "dictionaryFieldContext": { },
  • "filter": "@source==KnowledgeBase",
  • "licenseDefinitionKey": "string",
  • "pipeline": "InternalSearch",
  • "salesforceCommunityUrl": "string",
  • "salesforceFallbackToAdmin": true,
  • "salesforceOrganizationId": "00Df23090018W5bEAG",
  • "salesforceUser": "string",
  • "scope": 0,
  • "searchHub": "SupportHub",
  • "superUserToken": "string",
  • "userDisplayName": "Alice Smith",
  • "userGroups": [
    ],
  • "userIds": [
    ],
  • "usertype": "string",
  • "validFor": 3600000
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Get values for one field

Lists all values of the target field.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
field
required
string

The name of the field from which to retrieve values.

Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
object (RestCommerceParameters)
constantQueryOverride
string

A different constant query expression (cq) to use.

object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

dictionaryFieldContext
object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This parameter will be overridden if the request is authenticated by a search token that enforces a specific dictionaryFieldContext.

disjunctionQueryOverride
string

A different disjunction query expression (dq) to use.

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

ignoreAccents
boolean

Whether to treat accentuated characters as non-accentuated characters when retrieving field values (e.g., treat é, è, ê, etc., as e).

Default: true

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lookupField
string
Deprecated

This parameter is exposed for backward compatibility reasons.

The name of an additional field from which to retrieve values.

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumNumberOfValues
integer <int32> >= 0

The maximum number of field values to return.

Default: 10

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
pattern
string

The pattern that the field values must match.

See also the patternType parameter."

patternType
string

The type of pattern that is being used to list field values.

Use:

  • wildcard to parse the specified pattern as a wildcard expression.
  • regularexpression to parse the specified pattern as a regular expression.
  • editdistance to apply the Edit Distance algorithm to match values that are close to the specified pattern.
  • phonetic to apply a phonetic algorithm to match values that are phonetically similar to the specified pattern.

Default: wildcard

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

queryOverride
string

A different basic query expression (q) use.

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string or null

The sort criteria to use.

Use:

  • occurrences to sort by number of occurrences, with field values having the highest number of occurrences appearing first.
  • nosort to avoid sorting the results of the Group By operation. The field values will appear in an unspecified order.

Default: occurrences

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Request samples

Content type
application/json
{
  • "constantQueryOverride": "string",
  • "dictionaryFieldContext": { },
  • "disjunctionQueryOverride": "string",
  • "field": "@author",
  • "ignoreAccents": true,
  • "lookupField": "string",
  • "maximumNumberOfValues": 0,
  • "pattern": "string",
  • "patternType": "string",
  • "queryOverride": "string",
  • "sortCriteria": "string",
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "commerce": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get values for several field

Lists all values of the target field.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
object or null (AnalyticsRequestParameters)
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
required
Array of objects (RestListFieldValuesParameter)

An array of parameters to retrieve field values.

Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
object (RestCommerceParameters)
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Request samples

Content type
application/json
{
  • "batch": [
    ],
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "commerce": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "batch": [
    ]
}

Passages V3

Retrieves the passage(s) for a particular query.

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2apiKeyplatformTokenssearchTokens
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required
object

Localization parameter.

query
required
string <= 1000 characters

The query for which to retrieve the passage(s).

additionalFields
Array of strings <= 5 items [^([a-z][a-z0-9_]{0,254})$]

The fields to include in the response.

When omitted, only the identifier of the document will be returned.

object or null

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

filter
string

A filter expression that will be applied during the first stage retrieval.

The expression must comply with the Coveo Query Language (CQL) syntax.

maxPassages
integer <int32> [ 1 .. 20 ]
Default: 5

The maximum number of passage(s) to retrieve.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

Responses

Request samples

Content type
application/json
{
  • "additionalFields": [
    ],
  • "context": {
    },
  • "filter": "@source==\"acme\"\n",
  • "localization": {
    },
  • "maxPassages": 5,
  • "query": "What are the benefits of using solar energy?",
  • "searchHub": "Main"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "responseId": "c0857557-5579-4f5e-8958-9befd7d1d4a8"
}

Analysis V3

Convert query to structured expression

Parses a query expression written using the Coveo query syntax, and converts it into a structured expression. to a structured expression.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXPRESSION_VALIDATION_RESULT","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The query expression to parse and convert

query
required
string

A query using the Coveo query syntax.

Responses

Request samples

Content type
application/json
{
  • "query": "@altpopulation>=90000 AND @altcapital AND NOT (@source==\"Youtube\" OR @author==\"JohnSmith\")"
}

Response samples

Content type
application/json
{
  • "structured": {
    }
}

Replay a query with inspection details

Replay a query that was already done and get inspection details.

Note: This API call can only be used with an OAuth token. API Keys and Search Token aren't allowed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"REPLAY_ANY_QUERY","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

Inspection parameters

id
required
string

The SearchUID of the request to replay.

object

The date range within which to look for the request.

Responses

Request samples

Content type
application/json
{
  • "dateRange": {
    },
  • "id": "string"
}

Response samples

Content type
application/application+json
{
  • "execution": [
    ],
  • "requestParameters": {
    },
  • "results": [
    ],
  • "totalResultsCount": 0
}

Search

Send search request

See Performing a Query.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
Array of objects (ActionHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

Array
name
string

The action history event name.

Possible values:

  • Query
  • PageView
time
string

The time when the action history event was sent from the client.

value
any

The action history value, which is either a query expression or a page URI, depending on the action history event name.

object or null (AnalyticsRequestParameters)
actionCause
string

The type of operation that triggered this event. See Standard actions and Usage Analytics reference).

capture
boolean

Whether the search api call should be tracked for analytics and machine learning purposes. When set to true, be sure to set the actionCause parameter. See Standard actions and Usage Analytics reference).

clientId
string

A GUID which represents the current client.

If your implementation uses the Atomic or Headless libraries, or newer versions of the JavaScript Search Framework, then the client ID is generated automatically in client-side code. This GUID is held in a browser's local storage as well as a top level domain first-party cookie (coveo_visitorId) that expires after 1 year. Note: The cookie takes precedence over the value in the browser's local storage.

If you have a custom Coveo implementation, you will have to generate a UUID v4-formatted GUID. You will need to send this ID as analytics.clientId in every event that is sent to Coveo UA and the Search API.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note The clientId replaces the deprecated visitorId. For compatibility, the cookie and local storage values are still named coveo_visitorId.

clientRequestId
string

A GUID generated by the client representing the current request.

This information is used to identify operations across different apis related to the same request.

clientTimestamp
string

Client ISO 8601 timestamp with milliseconds.

customData
object

The user defined dimensions and their values. Keys can only contain alphanumeric or underscore characters. Whitespaces in keys are converted to underscores. Uppercase characters in keys are converted to lowercase characters. The value could be any valid JSON, but it is handled as string over Coveo usage analytics. It is highly recommended that you create your custom dimension before adding customData

documentLocation
string

The URL of the current page or component.

If not present, the referrer is obtained from the Referer header.

Note: This information can be obtained from coveo.analytics.js.

documentReferrer
string

Typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: This information can be obtained from coveo.analytics.js.

originContext
string

The origin of the event. Used to specify the deployment from which the user performs the action. Suggested values are Search, InternalSearch, CommunitySearch, or the originLevel1 value

(string or null) or integer

A GUID representing the page ID.

Note: This information can be obtained from coveo.analytics.js.

Any of
string or null

A GUID representing the page ID.

Note: This information can be obtained from coveo.analytics.js.

trackingId
string

A value to identify which web property an event is related to.

userAgent
string

The user agent of the request. If not present, the user agent is obtained from the User-Agent header.

Note: This information is required when endpoints are behind a proxy.

userId
string

The ID of the user who is currently logged in. If not present, this ID is obtained from the authentication token.

userIp
string

The user IP. If not present, the IP is obtained from the X-Forwarded-For and Forwarded headers.

Note: This information is required when endpoints are behind a proxy.

Example: 127.0. 0.1

aq
string

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

Array
field
required
string

The name of the field in which to look for hierarchical values.

Note: You must ensure that the Multi-value facet option is enabled for this field in your index (see Add or Edit Fields).

delimitingCharacter
string
Default: "|"

The character to use to split field values into a hierarchical sequence.

Example:

For a multi-value field containing the following values:

c; c>folder2; c>folder2>folder3;

The delimiting character is >.

Default: |

filterFacetCount
boolean

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: true

injectionDepth
integer <int32>
Default: 1000

The maximum number of query result items to scan.

Note: Specifying a high injectionDepth value can negatively impact query performance.

Default: 1000

maximumNumberOfValues
integer <int32> >= 0
Default: 10

The maximum number of values to return.

Default: 10

path
Array of strings

The retrieved sequence of hierarchical field values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object (RestCommerceParameters)

The parameters for Coveo for Commerce.

catalogId
string

The unique identifier of the catalog to query.

filter
string

A mandatory query expression to apply if the commerce request affects the query.

operation
string
Enum: "selectCatalogObjects" "excludeCatalogObjects"

The way the commerce request should affect query results.

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

dictionaryFieldContext
object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This cannot be used at the same time as fieldAliases.

Note: This parameter will be overridden if the search request is authenticated by a search token that enforces a specific dictionaryFieldContext.

disableQuerySyntax
boolean
Deprecated

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string

The disjunction query expression, typically populated by Coveo ML automatic relevance tuning models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)

The global configuration options that apply to all facet requests performed along with the query (see the facets query parameter).

enableIndexFacetOrdering
boolean
Default: true

Whether to take the scores generated by the index into account 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 disable automatic facet reordering entirely, set freezeFacetOrder to true instead.

Default: true

freezeFacetOrder
boolean
Default: false

Whether facets should be returned in the same order they were requested.

Note: Setting this to true entirely prevents automatic score-based 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.

Default: false

Array of any (RestFacetRequest)

The facet operations to perform on the query results.

Array
field
required
string

The name of the field on which to base the facet request.

Note: Must reference a field whose Facet option is enabled (see Add or Edit Fields).

type
required
string
Default: "specific"

The kind of values to request for the facet.

Allowed values:

  • specific: Request facet values representing specific values (e.g., Alice Smith, Bob Jones, etc.).
  • dateRange: Request facet values representing ranges of dates (e.g., 2019-07-01..2019-07-31, 2019-08-01..2019-08-01, etc.).
  • numericalRange: Request facet values representing ranges of numbers (e.g., 0..10, 11..20, etc.).
  • hierarchical: Request facet values representing hierarchically structured categories (e.g., Electronics > Entertainment > Gaming Consoles;, Electronics > Computers > Laptops, etc.).
Array of objects (RestFacetValueDateRange)
Default: []

The values displayed by the facet in the search interface at the moment of the request.

Array
end
required
string^\d{4}\/\d{2}\/\d{2}@\d{2}:\d{2}:\d{2}$

The value to end the range at. Must be greater (or later) than the start value.

Note: Timezone of date ranges are determined by the timezone parameter of the search request.

start
required
string^\d{4}\/\d{2}\/\d{2}@\d{2}:\d{2}:\d{2}$

The value to start the range at.

Note: Timezone of date ranges are determined by the timezone parameter of the search request.

endInclusive
boolean
Default: false

Whether to include the end value in the range.

preventAutoSelect
boolean
Default: false

Whether to prevent Coveo ML from automatically selecting the facet value.

state
string
Default: "idle"
Enum: "idle" "selected" "excluded"

The current facet value state in the search interface.

facetId
string

The unique identifier of the facet in the search interface.

Note: Must match `^[A-Za-z0-9-_]{1,60}$.

filterFacetCount
boolean
Default: true

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

freezeCurrentValues
boolean
Default: false

Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

Note:

  • Setting this to true keeps the facet from moving around while the end-user interacts with it in the search interface.
generateAutomaticRanges
boolean
Default: false

Whether to automatically generate range values for this facet.

Notes:

  • Setting this to true is only effective if the referenced field is of a corresponding type (i.e., date or numeric).
  • Automatic range generation will fail if the referenced field is dynamically generated by a query function.
  • Enabling the Use cache for numeric queries option on the referenced field will speed up automatic range generation.
injectionDepth
integer <int32>
Default: 1000

The maximum number of items to scan for facet values.

Note: A high injectionDepth may negatively impact the facet request performance.

isFieldExpanded
boolean
Default: false

Whether the facet is expanded in the search interface at the moment of the request.

numberOfValues
integer <int32>
Default: 8

The maximum number of facet values to fetch.

Note:

  • If freezeCurrentValues is true or generateAutomaticRanges is false, numberOfValues is automatically set to the length of the currentValues array.
preventAutoSelect
boolean
Default: false

Whether to prevent Coveo ML from automatically selecting values.

resultsMustMatch
string
Default: "atLeastOneValue"
Enum: "atLeastOneValue" "allValues"

Specifies how a result must match the selected values.

Allowed values:

  • atLeastOneValue: A result will match if at least one of the corresponding facet values is selected.
  • allValues: A result will match if all corresponding facet values are selected.

Default: atLeastOneValue

sortCriteria
string
Default: "ascending"

The criterion to use for sorting returned facet values.

Allowed values:

  • ascending: Sort in ascending order of range facet values.
  • descending: Sort in descending order of range facet values.
fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes:

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes:

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

Array
field
required
string

The name of the field on which to perform the Group By operation. The operation returns a Group By value for each distinct value of this field found in the query result items.

Note: You must ensure that the Facet option is enabled for this field in your index (see Add or Edit Fields).

advancedQueryOverride
string

The query expression that should override the advanced query expression on which the Group By operation is being performed (see the aq query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

allowedValues
Array of strings

The field values allowed in the Group By operation results. You can use trailing wildcards (*) to include ranges of values.

See also the completeFacetWithStandardValues Group By operation parameter.

If you do not explicitly specify an array of allowedValues, or if you specify an empty array, all field values are allowed.

Example:

[
  "Anonymous",
  "Bob Jones",
  "Carrie Green",
  "David Allen"
]
allowedValuesPatternType
string
Enum: "legacy" "wildcards" "regex" "editdistance" "phonetic"

The type of pattern being used in the allowed field values.

See also the allowedValues Group By operation parameter.

If you do not explicitly specify a pattern type, the legacy pattern is used by default, which only support trailing wildcards.

completeFacetWithStandardValues
boolean
Default: false

Whether to complete the Group By operation result set with standard values.

If you set this parameter to true and the number of specified allowedValues is lower than the maximumNumberOfValues, the Group By operation also attempts to returns standard values until the result set contains the maximumNumberOfValues.

Default: false

Array of objects (RestComputedField)

The computed fields to evaluate for each Group By value.

A computed field stores the result of an aggregate operation performed on the values of a specific numerical field for all the query result items that share the same Group By field value.

Array
field
required
string

The name of the numeric field on which to perform the aggregate operation.

Tip: You should ensure that the Use cache for computed fields option is enabled for that field in your index in order to speed up evaluation (see Add or Edit Fields).

operation
required
string
Enum: "sum" "average" "minimum" "maximum"

The aggregate operation to perform on the field values.

Allowed values:

  • sum: get the sum of all values.
  • average: get the average of all values.
  • minimum: get the smallest value.
  • maximum: get the largest value.
constantQueryOverride
string

The query expression that should override the constant query expression on which the Group By operation is being performed (see the cq query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

disjunctionQueryOverride
string

The query expression that should override the disjuntion query expression on which the Group By operation is being performed (see the dq query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

filterFacetCount
boolean
Default: true

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: true

generateAutomaticRanges
boolean
Default: false

Whether the index should automatically create range values.

Tip: If you set this parameter to true, you should ensure that the Use cache for numeric queries option is enabled for the Group By field in your index in order to speed up automatic range evaluation (see Add or Edit Fields).

Notes:

  • Setting generateAutomaticRanges to true only makes sense when the Group By field references a numeric or date field in the index.
  • The index cannot automatically generate range values of a field generated by a query function. In such cases, you must rather use the rangeValues Group By parameter.
  • Automatic range generation will fail if the referenced field is dynamically generated by a query function.

Default: false

injectionDepth
integer <int32>
Default: 1000

The maximum number of query result items to scan for Group By values.

Note: Specifying a high injectionDepth value can negatively impact query performance.

Default: 1000

lookupField
string
Deprecated

This property is exposed for backward compatibility reasons. The issues this property was used as a workaround for do not exist in the Coveo Cloud V2 platform.

The name of an additional field whose value must be retrieved.

maximumNumberOfValues
integer <int32> >= 0
Default: 10

The maximum number of values the Group By operation should return.

Default: 10

queryOverride
string

The query expression that should override the basic query expression on which the Group By operation is being performed (see the q query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

Array of objects (RestRangeValue)

The ranges for which to generate Group By values.

Notes:

  • Specifying rangeValues only makes sense when the Group By field references a numeric or date field in the index.
  • You can set the generateAutomaticRanges Group By parameter to true rather than explicitly specifying rangeValues (unless the Group By field was generated by a query function).
Array
required
string or number or integer
Any of
string
required
string or number or integer
Any of
string
endInclusive
boolean
Default: false

Whether to include the end value in the range.

Default: false

label
string

The label to associate with the range.

Note: Not currently leveraged.

Examples:

  • 0 - 100
  • In 2019
sortCriteria
string
Default: "score"

The criterion to use when sorting the Group By operation results.

Allowed values:

  • score: sort using the score value which is computed from the number of occurrences of a field value, as well as from the position where query result items having this field value appear in the ranked query result set. When using this sort criterion, a field value with 100 occurrences might appear after one with only 10 occurrences, if the occurrences of the latter field value tend to appear higher in the ranked query result set.
  • occurrences: sort by number of occurrences, with field values having the highest number of occurrences appearing first.
  • alphaAscending/alphaDescending: sort field values alphabetically.
  • alphaAscendingNatural/alphaDescendingNatural: sort field values alphabetically using natural sorting.
  • computedFieldAscending/computedFieldDescending: sort on the value of the first computed field for each Group By operation result (see the ComputedFields Group By parameter).
  • chiSquare: sort based on the relative frequency of field values in the query result set compared to their frequency in the entire index. This means that a field value that does not appear often in the index, but does appear often in the query result set will tend to appear higher.
  • noSort: do not sort the results of the Group By operation. The field values will be appear in a random order.

Default: score

thoroughLookup
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. The issues this parameter was used as a workaround for do not exist in the Coveo Cloud V2 platform.

Whether to scan for lookup values.

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

isGuestUser
boolean

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

language
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default: 100

lqPartialMatchThreshold
string

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer <int32>

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer <int32>

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

q
string

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

Array
fieldName
required
string

The name of the dynamic, temporary field in which to store the query function expression output.

Note: The fieldName value must not correspond to an existing field in the index.

function
required
string

The mathematical expression whose output should be stored in a dynamic, temporary field.

Notes:

  • The function expression can be defined using the ExprTk library syntax, but control and loop structures (e.g., if-then-else, while loop, etc.) are not supported.
  • If the function expression references a numeric field, enable the Use cache for computed fields option on that field to speed up evaluation (see Add or Edit Fields).
allowMissingFields
boolean
Default: false

Whether a document should be considered by the query function when one or more referenced fields are missing. When set to true, the missing fields will be assigned a NaN value, and the query function should handle NaN values by replacing them with a default value.

For example:

var price1 := @price == @price ? @price : 0;
var price2 := @price_store2 == @price_store2 ? @price_store2 : 0;
price1 + price2

Note: To be considered by the query function, a document must have at least one defined field. Documents with all fields missing will be excluded.

filter
string

A query expression to specify which result items that the query function should apply to.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

Array
expression
required
string

A mathematical expression to evaluate for each query result. The result of this expression for a given query result generates a boost which is then added to the ranking score of that query result.

Note: Query ranking function expressions support the ExprTk library syntax. However, the following statements are disabled:

  • if/else
  • switch
  • while
  • repeat until

The following time constants are also available in query ranking functions:

  • NOW: A value corresponding to the precise moment when the query reaches the index.
  • YEAR: A value corresponding to the duration of a year (i.e., 365.25 days).
  • WEEK: A value corresponding to the duration of a week.
  • DAY: A value corresponding to the duration of a day.

Tip: If your query ranking function expression references certain numeric fields, you should ensure that the Use cache for computed fields option is enabled for each of those fields in order to speed up evaluation (see Add or Edit Fields).

modifier
integer <int64>
Default: 600

The maximum boost this query ranking function can add to the ranking score of any given query result.

This property only has a meaning if normalizeWeight is set to true.

Default: 600

normalizeWeight
boolean
Default: false

Whether to normalize the ranking score boosts resulting from the evaluation of this query ranking function using the standard index scale.

Unless you want to completely override the index ranking and use the results of this query ranking function directly to boost the ranking scores of query results, you should set this to true.

Default: false

recommendation
string

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria which will be applied sequentially, i.e., if there's a tie on the 1st criterion, the API uses the 2nd criterion to break the tie. However, this only works when combining:

  • a relevancy criterion followed by one or more field or date criteria.
  • a qre criterion followed by one or more field or date criteria.
  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criterion and one or more field criteria in any order (e.g., @views descending, date ascending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)

The parameters allowing user actions to be retrieved in query results.

tagViewsOfUser
string

The user ID or visitor ID to retrieve user actions for.

Note: Only effective with authenticated users.

Examples:

  • asmith@example.com
  • c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e
viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

visitorId
string
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Response Schema:
apiVersion
required
integer <int32>

The version of the Search API that sent the query.

required
Array of objects (RestCategoryFacetResponse)

Hierarchical data results corresponding the to hierarchical data in the query.

Array
field
string
Array of objects (RestCategoryFacetValue)
Array
numberOfResults
integer <int64> >= 0
value
string
Array of objects (RestCategoryFacetValue)
Array
numberOfResults
integer <int64> >= 0
value
string
duration
required
integer <int32>

The requestDuration added to the computing time (in milliseconds) that was required by the Search API.

required
Array of objects (RestFacetResult)

The facet results returned by the query. These results are included in the order they were requested in the facets query parameter.

Array
field
required
string

The name of the field on which the facet is based.

**Example: author

indexScore
required
number <double>

The ranking score computed by the index for this facet.

moreValuesAvailable
required
boolean

Whether additional values are available for the facet.

required
Array of RestFacetResultValue (object) or RestHierarchicalFacetResponseValue (object)

The returned facet values.

Array
One of
numberOfResults
required
integer <int64>

The number of query results that can be expected if the facet value is selected in the search interface.

Note: This property only gets populated when the facet currently has no selected or excluded values.

state
required
string
Enum: "idle" "selected" "excluded"

The current facet value state in the search interface.

Default: idle

string or integer or number

The end of the range.

Any of
string

The end of the range.

endInclusive
boolean
Default: false

Whether to include the end value in the range.

Default: false

isAutoSelected
boolean

Whether the facet value was automatically selected by Coveo ML.

isSuggested
boolean
string or integer or number

The start of the range.

Any of
string

The start of the range.

value
string

The facet value name.

Note: In the case of a hierarchical facet value, this represents a single path segment.

object (RestFacetResultDomain)

The domain of the facet. It represents the lowest and highest values possible for this facet.

Note: This property is only populated when the facet is a range facet and generateAutomaticRanges: true was requested.

string or integer or number

The end of the domain. It represents the highest value possible for this facet.

Any of
string

The end of the domain. It represents the highest value possible for this facet.

string or integer or number

The start of the domain. It represents the lowest value possible for this facet.

Any of
string

The start of the domain. It represents the lowest value possible for this facet.

isFromAutoSelect
boolean

Whether the facet was recommended by Coveo ML.

label
string

A human-readable title that describes the facet.

mlScore
number <double>

The ranking score computed by Coveo ML DNE for this facet.

required
Array of objects (RestGroupByResult)

The Group By results returned by the query. These results are included in the order they were requested in the groupBy query parameter.

Array
field
required
string

The field on which the Group By operation was executed.

globalComputedFieldResults
required
Array of numbers <double> [ items <double > ]

The global computed fields that were processed by the index.

required
Array of objects (RestGroupByValue)

The resulting Group By values.

Array
computedFieldResults
required
Array of numbers <float> [ items <float > ]

The results of the computed fields (see the computedFields Group By parameter).

lookupValue
required
string
Deprecated

This property is deprecated; it should normally not be populated if the query was sent against a Coveo Cloud V2 index.

The lookup field value name.

numberOfResults
required
integer <int32>

The number of query result items having this field value.

score
required
integer <int32>

The Group By value score, computed from the numberOfResults value as well as from the position of the items having this value in the ranked query result set.

value
required
string

The Group By value name.

valueType
required
string

The type of Group By value.

ComputedFieldResults
Array of numbers <double> [ items <double > ]
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

LookupValue
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

NumberOfResults
integer <int32>
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Score
integer <int32>
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Value
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Field
string
Deprecated

This property is deprecated and Coveo Cloud V1 only; The lowercase field should be used instead.

GlobalComputedFieldResults
Array of numbers <double> [ items <double > ]
Deprecated

This property is deprecated and V1 only; The lowercase globalComputedFieldResults should be used instead.

index
required
string

The identifier of the index mirror against which the query was executed (see the indexToken query parameter).

indexDuration
required
integer <int32>

The time (in milliseconds) that was required by the index to find the query items.

required
object

The phrases to highlight in each query result item. This property is populated when the basic query expression (see the q query parameter) contains one or several exact phrase match requests (terms between double quote characters).

additional property
object
pipeline
required
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

required
Array of objects (RestQueryCorrection)

The query corrections suggested by the index, if the enableDidYouMean query parameter was set to true.

Array
correctedQuery
required
string

The resulting query expression correction suggestion.

required
Array of objects (RestWordCorrection)

The word correction suggestions.

Array
correctedWord
required
string

The suggested word correction.

length
required
integer <int32>

The length (in number of characters) of the corrected word.

offset
required
integer <int32>

The offset (in number of characters) of the corrected word, from the beginning of the resulting query expression correction suggestion.

originalWord
required
string

The original, un-corrected word.

refinedKeywords
required
Array of strings

The refined keywords used by the Coveo ML automatic relevance tuning model.

requestDuration
required
integer <int32>

The indexDuration added to the time (in milliseconds) that was required to establish a connection between the Search API server and the index server.

required
Array of objects (RestQueryResult)

The items returned for the query.

Array
absentTerms
required
Array of strings

The basic query expression terms which this query result item does not match.

Note:

This property is populated by terms from the query pipeline-processed q value (not from the original q value).

required
Array of RestQueryResult (object)

An array of references to the children of this item, if result folding was applied (see the filterField query parameter). The query results contained in this field will have both their parent and child results set to null.

Array
Any of
object RestQueryResult Recursive
clickUri
required
string

The hyperlinkable item URI.

Notes:

  • Use the clickUri value when you want to create hyperlinks to the item, rather than the uri or printableUri value.
  • The clickUri value is not necessarily unique for each item.
excerpt
required
string

The contextual excerpt generated for the item (see the excerptLength query parameter).

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item excerpt string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

firstSentences
required
string or null

The first sentences retrieved from the item (see the retrieveFirstSentences query parameter).

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item firstSentences string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

flags
required
string

The flags that are set on the item by the index. Distinct values are separated by semicolons.

hasHtmlVersion
required
boolean

Whether the index contains an HTML version of this item.

hasMobileHtmlVersion
required
boolean

Whether the index contains a mobile HTML version of this item.

isRecommendation
required
boolean

Whether the item score was boosted as a Coveo ML recommendation.

isTopResult
required
boolean

Whether the item score was boosted by a featured result rule in the query pipeline.

isUserActionView
required
boolean

Whether the item score was boosted as a Coveo ML recommendation.

parentResult
required
object or null (RestQueryParentResult) Recursive
percentScore
required
number <double>

The item ranking score expressed as a percentage (see the sortCriteria and rankingFunctions query parameters).

printableUri
required
string

The human readable item URI.

Note: Avoid using the printableUri value to create hyperlinks to the item. Use the ClickUri value instead.

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item printableUri string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

rankingInfo
required
string

The raw debug information generated by the index to detail how the item was ranked. This property is null unless the debug query parameter is set to true.

rating
required
number <double>

The item rating (see the enableCollaborativeRating query parameter).

Note: Unless collaborative rating is enabled for your index, the value of this property is always 3.

required
object

The values of the fields which were retrieved for this item (see the fieldsToInclude and fieldsToExclude query parameters).

property name*
additional property
any
score
required
integer <int32>

The total ranking score computed for the item (see the sortCriteria and rankingFunctions query parameters).

summary
required
string or null

The item summary (see the summaryLength query parameter).

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item summary string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

title
required
string

The item title.

Note: When logging a Click usage analytics event for an opened query result item, the documentTitle field of that event should be set to the title value of the opened query result item.

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item title string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

totalNumberOfChildResults
required
integer <int64>

The total number of children available in the index for this item, if result folding was applied (see the filterField query parameter).

uniqueId
required
string

The unique item identifier. You should consider the uniqueId value as an opaque string.

uri
required
string

The item URI.

Notes:

  • Avoid using the uri value to create hyperlinks to the item. Use the ClickUri value instead.
  • When logging a Click usage analytics event for an opened query result item, the documentUrl field of that event should be set to the uri value of the opened query result item.
ClickUri
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Excerpt
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

FirstSentences
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

PrintableUri
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

rankingModifier
string

If applicable, represents the type of ranking modification that was applied to this result.

Note: When logging a Click usage analytics event for an opened query result item, the rankingModifier field of that event should be set to the rankingModifier value of the opened query result item, if available.

Title
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

UniqueId
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Uri
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

searchUid
required
string

The query UUID. Each query sent to the Search API has its own randomly generated searchUid.

Note: When logging a Search or Custom usage analytics event for a query, or a Click usage analytics event for an opened query result item, the searchQueryUid field of that event should be set to the searchUid value of the query response.

required
Array of objects (RestSuggestedFacet)

A DNE facet suggestion.

Array
field
required
string

The name of the field on which the DNE facet suggestion is based.

Example: author

required
Array of objects (RestSuggestedFacetValue)

The name of the field on which the DNE facet suggestion is based.

Example: author

Array
value
required
string

A DNE facet value suggestion.

Example: Alice Smith

path
Array of strings

The path to the suggested facet value (only applies to hierarchical facet value suggestions).

Example: If the suggested hierarchical facet value is Parrot, the returned path could be ["Animals", "Birds", "Parrot"].

required
object

The terms to highlight in each query result item. Includes all basic query expression keywords, as well as any word stemmed from a basic query expression keyword (see the q query parameter), unless this keyword was preceded by the no stemming Coveo Cloud query syntax operator (+).

property name*
additional property
Array of strings
totalCount
required
integer <int32>

The total number of items matching the query for the current user (security trimming applied).

Note: When logging a Search usage analytics event for a query, the numberOfResults field of that event should be set to the totalCount value of the query (for reporting purposes).

totalCountFiltered
required
integer <int32>

The total number of items matching the query for the current user (security trimming applied) after duplicate filtering has been applied (see the duplicateFiltering query parameter).

required
Array of objects (RestTriggerResponse)

The actions to perform by the client based on the Trigger statements defined in query pipelines (see the pipeline query parameter).

Note:

A Trigger statement must have a condition. Otherwise, the Search API ignores it and does not include it in the triggers array of the query response (see Managing Query Pipeline Triggers).

Array
content
required
any
type
required
string
Enum: "notify" "execute" "query" "redirect"

The type of Coveo Cloud query pipeline Trigger statement (see Managing Query Pipeline Triggers).

errors
Array of strings

The errors that critically changed the query behaviour. These should be addressed right away to prevent future errors.

object (RestException)
code
required
string
context
string
object

Additional response attributes coming from the execution of query pipeline integrations.

Currently supported properties:

  • generativeQuestionAnsweringId: A stream ID to access the generated answer.
property name*
additional property
string
object

Automatically generated facets based on the generateAutomaticFacets request parameter.

Array of objects (RestFacetResult)
indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

isFallbackToAdmin
boolean

Whether the admin session ID was allowed and used by the Coveo for Salesforce search engine. The value will be set to true when it is the case, and might be absent or set to false otherwise.

object

Property returned when the queryCorrection feature is enabled.

It will either return:

  • The originalQuery and correctedQuery if the query was automatically corrected.
  • A list of corrections that could be be manually applied afterward.
correctedQuery
string

If the query was automatically corrected, this property indicates the corrected basic query expression (q) that was executed instead of the original one.

Array of objects (RestQueryCorrection)

If the query wasn't automatically corrected, this property contains the basic query expression (q) keyword corrections suggested by the Did You Mean index feature.

Array
correctedQuery
required
string

The resulting query expression correction suggestion.

required
Array of objects (RestWordCorrection)

The word correction suggestions.

Array
correctedWord
required
string

The suggested word correction.

length
required
integer <int32>

The length (in number of characters) of the corrected word.

offset
required
integer <int32>

The offset (in number of characters) of the corrected word, from the beginning of the resulting query expression correction suggestion.

originalWord
required
string

The original, un-corrected word.

originalQuery
string

If the query was automatically corrected, this property indicates the original basic query expression (q) that triggered the automatic query correction.

object (RestQuestionAnswer)
answerFound
required
boolean
answerSnippet
required
string
required
object (RestContentId)
contentIdKey
required
string
contentIdValue
required
string
question
required
string
required
Array of objects
Array
answerSnippet
required
string
required
object (RestContentId)
contentIdKey
required
string
contentIdValue
required
string
question
required
string
score
required
number
score
required
number
object
property name*
additional property
any
splitTestRun
string

Whether there is an active A/B test on the query pipeline. If not, this attribute will not appear in the response. It is used to identify and differentiate between A/B tests, and is crucial for tracking and analyzing the performance of different A/B test configurations.

warnings
Array of strings

The errors that did not make the query fail, but should be addressed. They might be security issues, deprecated behaviors, or any other kind of concern.

Response samples

Content type
{
  • "apiVersion": 2,
  • "categoryFacets": [
    ],
  • "duration": 1235,
  • "errors": [
    ],
  • "exception": {
    },
  • "extendedResults": {
    },
  • "facets": [
    ],
  • "generateAutomaticFacets": {
    },
  • "groupByResults": [
    ],
  • "index": "mycoveocloudv2organizationid-cqjd206sta1xb9qyxfhhnsu294-Indexer-2-9rbfxhp1n07cth80ckzeh3zotc",
  • "indexDuration": 1175,
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "isFallbackToAdmin": true,
  • "phrasesToHighlight": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "queryCorrection": {
    },
  • "queryCorrections": [ ],
  • "questionAnswer": {
    },
  • "refinedKeywords": [
    ],
  • "requestDuration": 1181,
  • "results": [
    ],
  • "searchUid": "a0e4773c-39c3-423c-90cd-c03a640ecde5",
  • "splitTestRun": "CustomerQueryPipeline-mirror-1725560351",
  • "suggestedFacets": [
    ],
  • "termsToHighlight": {
    },
  • "totalCount": 250,
  • "totalCountFiltered": 245,
  • "triggers": [
    ],
  • "warnings": [
    ]
}

Send search request

See Performing a Query.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

Array
name
string

The action history event name.

Possible values:

  • Query
  • PageView
time
string

The time when the action history event was sent from the client.

value
any

The action history value, which is either a query expression or a page URI, depending on the action history event name.

object or null (AnalyticsRequestParameters)
actionCause
string

The type of operation that triggered this event. See Standard actions and Usage Analytics reference).

capture
boolean

Whether the search api call should be tracked for analytics and machine learning purposes. When set to true, be sure to set the actionCause parameter. See Standard actions and Usage Analytics reference).

clientId
string

A GUID which represents the current client.

If your implementation uses the Atomic or Headless libraries, or newer versions of the JavaScript Search Framework, then the client ID is generated automatically in client-side code. This GUID is held in a browser's local storage as well as a top level domain first-party cookie (coveo_visitorId) that expires after 1 year. Note: The cookie takes precedence over the value in the browser's local storage.

If you have a custom Coveo implementation, you will have to generate a UUID v4-formatted GUID. You will need to send this ID as analytics.clientId in every event that is sent to Coveo UA and the Search API.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note The clientId replaces the deprecated visitorId. For compatibility, the cookie and local storage values are still named coveo_visitorId.

clientRequestId
string

A GUID generated by the client representing the current request.

This information is used to identify operations across different apis related to the same request.

clientTimestamp
string

Client ISO 8601 timestamp with milliseconds.

customData
object

The user defined dimensions and their values. Keys can only contain alphanumeric or underscore characters. Whitespaces in keys are converted to underscores. Uppercase characters in keys are converted to lowercase characters. The value could be any valid JSON, but it is handled as string over Coveo usage analytics. It is highly recommended that you create your custom dimension before adding customData

documentLocation
string

The URL of the current page or component.

If not present, the referrer is obtained from the Referer header.

Note: This information can be obtained from coveo.analytics.js.

documentReferrer
string

Typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: This information can be obtained from coveo.analytics.js.

originContext
string

The origin of the event. Used to specify the deployment from which the user performs the action. Suggested values are Search, InternalSearch, CommunitySearch, or the originLevel1 value

(string or null) or integer

A GUID representing the page ID.

Note: This information can be obtained from coveo.analytics.js.

Any of
string or null

A GUID representing the page ID.

Note: This information can be obtained from coveo.analytics.js.

trackingId
string

A value to identify which web property an event is related to.

userAgent
string

The user agent of the request. If not present, the user agent is obtained from the User-Agent header.

Note: This information is required when endpoints are behind a proxy.

userId
string

The ID of the user who is currently logged in. If not present, this ID is obtained from the authentication token.

userIp
string

The user IP. If not present, the IP is obtained from the X-Forwarded-For and Forwarded headers.

Note: This information is required when endpoints are behind a proxy.

Example: 127.0. 0.1

aq
string (AQ)

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

Array
field
required
string

The name of the field in which to look for hierarchical values.

Note: You must ensure that the Multi-value facet option is enabled for this field in your index (see Add or Edit Fields).

delimitingCharacter
string
Default: "|"

The character to use to split field values into a hierarchical sequence.

Example:

For a multi-value field containing the following values:

c; c>folder2; c>folder2>folder3;

The delimiting character is >.

Default: |

filterFacetCount
boolean

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: true

injectionDepth
integer <int32>
Default: 1000

The maximum number of query result items to scan.

Note: Specifying a high injectionDepth value can negatively impact query performance.

Default: 1000

maximumNumberOfValues
integer <int32> >= 0
Default: 10

The maximum number of values to return.

Default: 10

path
Array of strings

The retrieved sequence of hierarchical field values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object
catalogId
string

The unique identifier of the catalog to query.

filter
string

A mandatory query expression to apply if the commerce request affects the query.

operation
string
Enum: "selectCatalogObjects" "excludeCatalogObjects"

The way the commerce request should affect query results.

object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

property name*
additional property
any
cq
string (CQ)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

property name*
additional property
string
disableQuerySyntax
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string (DQ)

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean
Default: false

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean
Default: false

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean
Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean
Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean
Default: true

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>
Default: 200

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)
enableIndexFacetOrdering
boolean
Default: true

Whether to take the scores generated by the index into account 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 disable automatic facet reordering entirely, set freezeFacetOrder to true instead.

Default: true

freezeFacetOrder
boolean
Default: false

Whether facets should be returned in the same order they were requested.

Note: Setting this to true entirely prevents automatic score-based 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.

Default: false

Array of any (RestFacetRequest)

The facet operations to perform on the query results.

Array
field
required
string

The name of the field on which to base the facet request.

Note: Must reference a field whose Facet option is enabled (see Add or Edit Fields).

type
required
string
Default: "specific"

The kind of values to request for the facet.

Allowed values:

  • specific: Request facet values representing specific values (e.g., Alice Smith, Bob Jones, etc.).
  • dateRange: Request facet values representing ranges of dates (e.g., 2019-07-01..2019-07-31, 2019-08-01..2019-08-01, etc.).
  • numericalRange: Request facet values representing ranges of numbers (e.g., 0..10, 11..20, etc.).
  • hierarchical: Request facet values representing hierarchically structured categories (e.g., Electronics > Entertainment > Gaming Consoles;, Electronics > Computers > Laptops, etc.).
Array of objects (RestFacetValueDateRange)
Default: []

The values displayed by the facet in the search interface at the moment of the request.

Array
end
required
string^\d{4}\/\d{2}\/\d{2}@\d{2}:\d{2}:\d{2}$

The value to end the range at. Must be greater (or later) than the start value.

Note: Timezone of date ranges are determined by the timezone parameter of the search request.

start
required
string^\d{4}\/\d{2}\/\d{2}@\d{2}:\d{2}:\d{2}$

The value to start the range at.

Note: Timezone of date ranges are determined by the timezone parameter of the search request.

endInclusive
boolean
Default: false

Whether to include the end value in the range.

preventAutoSelect
boolean
Default: false

Whether to prevent Coveo ML from automatically selecting the facet value.

state
string
Default: "idle"
Enum: "idle" "selected" "excluded"

The current facet value state in the search interface.

facetId
string

The unique identifier of the facet in the search interface.

Note: Must match `^[A-Za-z0-9-_]{1,60}$.

filterFacetCount
boolean
Default: true

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

freezeCurrentValues
boolean
Default: false

Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

Note:

  • Setting this to true keeps the facet from moving around while the end-user interacts with it in the search interface.
generateAutomaticRanges
boolean
Default: false

Whether to automatically generate range values for this facet.

Notes:

  • Setting this to true is only effective if the referenced field is of a corresponding type (i.e., date or numeric).
  • Automatic range generation will fail if the referenced field is dynamically generated by a query function.
  • Enabling the Use cache for numeric queries option on the referenced field will speed up automatic range generation.
injectionDepth
integer <int32>
Default: 1000

The maximum number of items to scan for facet values.

Note: A high injectionDepth may negatively impact the facet request performance.

isFieldExpanded
boolean
Default: false

Whether the facet is expanded in the search interface at the moment of the request.

numberOfValues
integer <int32>
Default: 8

The maximum number of facet values to fetch.

Note:

  • If freezeCurrentValues is true or generateAutomaticRanges is false, numberOfValues is automatically set to the length of the currentValues array.
preventAutoSelect
boolean
Default: false

Whether to prevent Coveo ML from automatically selecting values.

resultsMustMatch
string
Default: "atLeastOneValue"
Enum: "atLeastOneValue" "allValues"

Specifies how a result must match the selected values.

Allowed values:

  • atLeastOneValue: A result will match if at least one of the corresponding facet values is selected.
  • allValues: A result will match if all corresponding facet values are selected.

Default: atLeastOneValue

sortCriteria
string
Default: "ascending"

The criterion to use for sorting returned facet values.

Allowed values:

  • ascending: Sort in ascending order of range facet values.
  • descending: Sort in descending order of range facet values.
fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>
Default: 5

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>
Default: 0

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

object

Generate facets based on the most relevant fields in the index.

Array of objects
Array
required
Array of objects (RestFacetSpecificValue)

The values displayed by the facet in the search interface at the moment of the request.

Default: []

Array
value
required
string

The facet value name.

preventAutoSelect
boolean
Default: false

Whether to prevent Coveo ML from automatically selecting the facet value.

state
string
Default: "idle"
Enum: "idle" "selected" "excluded"

The current facet value state in the search interface.

field
required
string

The name of the field on which to base the facet request.

Note: Must reference a field whose Facet option is enabled (see Add or Edit Fields).

label
string

A human-readable title that describes the facet.

type
string
Value: "specific"

Request facet values representing specific values (e.g., Alice Smith, Bob Jones, etc.).

desiredCount
integer <int32> [ 0 .. 20 ]

The desired number of automatically generated facets.

object (RestAutomaticFacetScope)

To determine which fields are relevant for the current query, we consider all facet and multi-value facet fields that have the parameter "automaticFacetsCandidate": true. Among these fields, those matching the "fields.toExclude" attribute within the query/pipeline payload will be excluded and no longer be considered as relevant. However, excluded fields that do match the "fields.toInclude" attribute within the query/pipeline payload will still be considered relevant.

toExclude
Array of strings
toInclude
Array of strings
generationStrategy
string
Default: "mostRelevant"
Enum: "mostRelevant" "matchDesiredCount"

Defines the strategy used to decide which facets will be automatically generated.

  • mostRelevant: Returns a maximum of desiredCount relevant facets. If fewer relevant facets are available, only those will be returned. This option prioritizes quality over quantity.
  • matchDesiredCount: Returns all available desiredCount facets in your organization, even if some have lower relevance. This option prioritizes quantity over quality.
numberOfValues
integer <int32> >= 1
Default: 8

The desired number of automatically generated facet values.

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

Array
field
required
string

The name of the field on which to perform the Group By operation. The operation returns a Group By value for each distinct value of this field found in the query result items.

Note: You must ensure that the Facet option is enabled for this field in your index (see Add or Edit Fields).

advancedQueryOverride
string

The query expression that should override the advanced query expression on which the Group By operation is being performed (see the aq query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

allowedValues
Array of strings

The field values allowed in the Group By operation results. You can use trailing wildcards (*) to include ranges of values.

See also the completeFacetWithStandardValues Group By operation parameter.

If you do not explicitly specify an array of allowedValues, or if you specify an empty array, all field values are allowed.

Example:

[
  "Anonymous",
  "Bob Jones",
  "Carrie Green",
  "David Allen"
]
allowedValuesPatternType
string
Enum: "legacy" "wildcards" "regex" "editdistance" "phonetic"

The type of pattern being used in the allowed field values.

See also the allowedValues Group By operation parameter.

If you do not explicitly specify a pattern type, the legacy pattern is used by default, which only support trailing wildcards.

completeFacetWithStandardValues
boolean
Default: false

Whether to complete the Group By operation result set with standard values.

If you set this parameter to true and the number of specified allowedValues is lower than the maximumNumberOfValues, the Group By operation also attempts to returns standard values until the result set contains the maximumNumberOfValues.

Default: false

Array of objects (RestComputedField)

The computed fields to evaluate for each Group By value.

A computed field stores the result of an aggregate operation performed on the values of a specific numerical field for all the query result items that share the same Group By field value.

Array
field
required
string

The name of the numeric field on which to perform the aggregate operation.

Tip: You should ensure that the Use cache for computed fields option is enabled for that field in your index in order to speed up evaluation (see Add or Edit Fields).

operation
required
string
Enum: "sum" "average" "minimum" "maximum"

The aggregate operation to perform on the field values.

Allowed values:

  • sum: get the sum of all values.
  • average: get the average of all values.
  • minimum: get the smallest value.
  • maximum: get the largest value.
constantQueryOverride
string

The query expression that should override the constant query expression on which the Group By operation is being performed (see the cq query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

disjunctionQueryOverride
string

The query expression that should override the disjuntion query expression on which the Group By operation is being performed (see the dq query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

filterFacetCount
boolean
Default: true

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: true

generateAutomaticRanges
boolean
Default: false

Whether the index should automatically create range values.

Tip: If you set this parameter to true, you should ensure that the Use cache for numeric queries option is enabled for the Group By field in your index in order to speed up automatic range evaluation (see Add or Edit Fields).

Notes:

  • Setting generateAutomaticRanges to true only makes sense when the Group By field references a numeric or date field in the index.
  • The index cannot automatically generate range values of a field generated by a query function. In such cases, you must rather use the rangeValues Group By parameter.
  • Automatic range generation will fail if the referenced field is dynamically generated by a query function.

Default: false

injectionDepth
integer <int32>
Default: 1000

The maximum number of query result items to scan for Group By values.

Note: Specifying a high injectionDepth value can negatively impact query performance.

Default: 1000

lookupField
string
Deprecated

This property is exposed for backward compatibility reasons. The issues this property was used as a workaround for do not exist in the Coveo Cloud V2 platform.

The name of an additional field whose value must be retrieved.

maximumNumberOfValues
integer <int32> >= 0
Default: 10

The maximum number of values the Group By operation should return.

Default: 10

queryOverride
string

The query expression that should override the basic query expression on which the Group By operation is being performed (see the q query parameter).

Note: If any query override parameter (e.g., queryOverride, advancedQueryOverride, etc.) is set in a Group By operation, all original parts of the query expression (i.e., q, aq, cq, and dq) will be ignored.

Array of objects (RestRangeValue)

The ranges for which to generate Group By values.

Notes:

  • Specifying rangeValues only makes sense when the Group By field references a numeric or date field in the index.
  • You can set the generateAutomaticRanges Group By parameter to true rather than explicitly specifying rangeValues (unless the Group By field was generated by a query function).
Array
required
string or number or integer
Any of
string
required
string or number or integer
Any of
string
endInclusive
boolean
Default: false

Whether to include the end value in the range.

Default: false

label
string

The label to associate with the range.

Note: Not currently leveraged.

Examples:

  • 0 - 100
  • In 2019
sortCriteria
string
Default: "score"

The criterion to use when sorting the Group By operation results.

Allowed values:

  • score: sort using the score value which is computed from the number of occurrences of a field value, as well as from the position where query result items having this field value appear in the ranked query result set. When using this sort criterion, a field value with 100 occurrences might appear after one with only 10 occurrences, if the occurrences of the latter field value tend to appear higher in the ranked query result set.
  • occurrences: sort by number of occurrences, with field values having the highest number of occurrences appearing first.
  • alphaAscending/alphaDescending: sort field values alphabetically.
  • alphaAscendingNatural/alphaDescendingNatural: sort field values alphabetically using natural sorting.
  • computedFieldAscending/computedFieldDescending: sort on the value of the first computed field for each Group By operation result (see the ComputedFields Group By parameter).
  • chiSquare: sort based on the relative frequency of field values in the query result set compared to their frequency in the entire index. This means that a field value that does not appear often in the index, but does appear often in the query result set will tend to appear higher.
  • noSort: do not sort the results of the Group By operation. The field values will be appear in a random order.

Default: score

thoroughLookup
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. The issues this parameter was used as a workaround for do not exist in the Coveo Cloud V2 platform.

Whether to scan for lookup values.

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean
Default: false

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string (LQ)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer <int32>
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

lqPartialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>
Default: 3

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>
Default: 1

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean
Default: false

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0
Default: 10

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean
Default: false

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

property name*
additional property
any
q
string (Q)

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

object

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

  • Attempt to correct your query if it doesn't return enough results.
  • If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

  • The original query
  • The corrected query

Otherwise, it will return:

  • A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

enabled
required
boolean

Whether or not this feature should be enabled. If it's set to false, other queryCorrection properties will be ignored.

Note: You don't have to set enableDidYouMean or enableMlDidYouMean to use this feature. The queryCorrection parameter takes precedence over them.

object
automaticallyCorrect
string
Default: "whenNoResults"
Enum: "never" "whenNoResults"

If set to whenNoResults, there are no results returned by the query and the original basic query expression (q) appears to have been misspelled, the Search API will attempt to correct the q value by either:

  • applying keyword corrections, if any were provided by the Did You Mean index feature, or otherwise
  • replacing the original q value with the highest ranked Coveo ML query suggestion that will return results.

If the q value was corrected, the Search API will then automatically fetch results from the index using the corrected q rather than the original one.

If set to never, potential corrections found by the Did You Mean index feature will be returned instead of being automatically applied.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

Array
fieldName
required
string

The name of the dynamic, temporary field in which to store the query function expression output.

Note: The fieldName value must not correspond to an existing field in the index.

function
required
string

The mathematical expression whose output should be stored in a dynamic, temporary field.

Notes:

  • The function expression can be defined using the ExprTk library syntax, but control and loop structures (e.g., if-then-else, while loop, etc.) are not supported.
  • If the function expression references a numeric field, enable the Use cache for computed fields option on that field to speed up evaluation (see Add or Edit Fields).
allowMissingFields
boolean
Default: false

Whether a document should be considered by the query function when one or more referenced fields are missing. When set to true, the missing fields will be assigned a NaN value, and the query function should handle NaN values by replacing them with a default value.

For example:

var price1 := @price == @price ? @price : 0;
var price2 := @price_store2 == @price_store2 ? @price_store2 : 0;
price1 + price2

Note: To be considered by the query function, a document must have at least one defined field. Documents with all fields missing will be excluded.

filter
string

A query expression to specify which result items that the query function should apply to.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

Array
expression
required
string

A mathematical expression to evaluate for each query result. The result of this expression for a given query result generates a boost which is then added to the ranking score of that query result.

Note: Query ranking function expressions support the ExprTk library syntax. However, the following statements are disabled:

  • if/else
  • switch
  • while
  • repeat until

The following time constants are also available in query ranking functions:

  • NOW: A value corresponding to the precise moment when the query reaches the index.
  • YEAR: A value corresponding to the duration of a year (i.e., 365.25 days).
  • WEEK: A value corresponding to the duration of a week.
  • DAY: A value corresponding to the duration of a day.

Tip: If your query ranking function expression references certain numeric fields, you should ensure that the Use cache for computed fields option is enabled for each of those fields in order to speed up evaluation (see Add or Edit Fields).

modifier
integer <int64>
Default: 600

The maximum boost this query ranking function can add to the ranking score of any given query result.

This property only has a meaning if normalizeWeight is set to true.

Default: 600

normalizeWeight
boolean
Default: false

Whether to normalize the ranking score boosts resulting from the evaluation of this query ranking function using the standard index scale.

Unless you want to completely override the index ranking and use the results of this query ranking function directly to boost the ranking scores of query results, you should set this to true.

Default: false

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean
Default: false

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string
Default: "Relevancy"

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean
Default: false

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>
Default: 0

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)
tagViewsOfUser
string

The user ID or visitor ID to retrieve user actions for.

Note: Only effective with authenticated users.

Examples:

  • asmith@example.com
  • c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e
visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean
Default: false

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Response Schema:
apiVersion
required
integer <int32>

The version of the Search API that sent the query.

required
Array of objects (RestCategoryFacetResponse)

Hierarchical data results corresponding the to hierarchical data in the query.

Array
field
string
Array of objects (RestCategoryFacetValue)
Array
numberOfResults
integer <int64> >= 0
value
string
Array of objects (RestCategoryFacetValue)
Array
numberOfResults
integer <int64> >= 0
value
string
duration
required
integer <int32>

The requestDuration added to the computing time (in milliseconds) that was required by the Search API.

required
Array of objects (RestFacetResult)

The facet results returned by the query. These results are included in the order they were requested in the facets query parameter.

Array
field
required
string

The name of the field on which the facet is based.

**Example: author

indexScore
required
number <double>

The ranking score computed by the index for this facet.

moreValuesAvailable
required
boolean

Whether additional values are available for the facet.

required
Array of RestFacetResultValue (object) or RestHierarchicalFacetResponseValue (object)

The returned facet values.

Array
One of
numberOfResults
required
integer <int64>

The number of query results that can be expected if the facet value is selected in the search interface.

Note: This property only gets populated when the facet currently has no selected or excluded values.

state
required
string
Enum: "idle" "selected" "excluded"

The current facet value state in the search interface.

Default: idle

string or integer or number

The end of the range.

Any of
string

The end of the range.

endInclusive
boolean
Default: false

Whether to include the end value in the range.

Default: false

isAutoSelected
boolean

Whether the facet value was automatically selected by Coveo ML.

isSuggested
boolean
string or integer or number

The start of the range.

Any of
string

The start of the range.

value
string

The facet value name.

Note: In the case of a hierarchical facet value, this represents a single path segment.

object (RestFacetResultDomain)

The domain of the facet. It represents the lowest and highest values possible for this facet.

Note: This property is only populated when the facet is a range facet and generateAutomaticRanges: true was requested.

string or integer or number

The end of the domain. It represents the highest value possible for this facet.

Any of
string

The end of the domain. It represents the highest value possible for this facet.

string or integer or number

The start of the domain. It represents the lowest value possible for this facet.

Any of
string

The start of the domain. It represents the lowest value possible for this facet.

isFromAutoSelect
boolean

Whether the facet was recommended by Coveo ML.

label
string

A human-readable title that describes the facet.

mlScore
number <double>

The ranking score computed by Coveo ML DNE for this facet.

required
Array of objects (RestGroupByResult)

The Group By results returned by the query. These results are included in the order they were requested in the groupBy query parameter.

Array
field
required
string

The field on which the Group By operation was executed.

globalComputedFieldResults
required
Array of numbers <double> [ items <double > ]

The global computed fields that were processed by the index.

required
Array of objects (RestGroupByValue)

The resulting Group By values.

Array
computedFieldResults
required
Array of numbers <float> [ items <float > ]

The results of the computed fields (see the computedFields Group By parameter).

lookupValue
required
string
Deprecated

This property is deprecated; it should normally not be populated if the query was sent against a Coveo Cloud V2 index.

The lookup field value name.

numberOfResults
required
integer <int32>

The number of query result items having this field value.

score
required
integer <int32>

The Group By value score, computed from the numberOfResults value as well as from the position of the items having this value in the ranked query result set.

value
required
string

The Group By value name.

valueType
required
string

The type of Group By value.

ComputedFieldResults
Array of numbers <double> [ items <double > ]
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

LookupValue
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

NumberOfResults
integer <int32>
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Score
integer <int32>
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Value
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Field
string
Deprecated

This property is deprecated and Coveo Cloud V1 only; The lowercase field should be used instead.

GlobalComputedFieldResults
Array of numbers <double> [ items <double > ]
Deprecated

This property is deprecated and V1 only; The lowercase globalComputedFieldResults should be used instead.

index
required
string

The identifier of the index mirror against which the query was executed (see the indexToken query parameter).

indexDuration
required
integer <int32>

The time (in milliseconds) that was required by the index to find the query items.

required
object

The phrases to highlight in each query result item. This property is populated when the basic query expression (see the q query parameter) contains one or several exact phrase match requests (terms between double quote characters).

additional property
object
pipeline
required
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

required
Array of objects (RestQueryCorrection)

The query corrections suggested by the index, if the enableDidYouMean query parameter was set to true.

Array
correctedQuery
required
string

The resulting query expression correction suggestion.

required
Array of objects (RestWordCorrection)

The word correction suggestions.

Array
correctedWord
required
string

The suggested word correction.

length
required
integer <int32>

The length (in number of characters) of the corrected word.

offset
required
integer <int32>

The offset (in number of characters) of the corrected word, from the beginning of the resulting query expression correction suggestion.

originalWord
required
string

The original, un-corrected word.

refinedKeywords
required
Array of strings

The refined keywords used by the Coveo ML automatic relevance tuning model.

requestDuration
required
integer <int32>

The indexDuration added to the time (in milliseconds) that was required to establish a connection between the Search API server and the index server.

required
Array of objects (RestQueryResult)

The items returned for the query.

Array
absentTerms
required
Array of strings

The basic query expression terms which this query result item does not match.

Note:

This property is populated by terms from the query pipeline-processed q value (not from the original q value).

required
Array of RestQueryResult (object)

An array of references to the children of this item, if result folding was applied (see the filterField query parameter). The query results contained in this field will have both their parent and child results set to null.

Array
Any of
object RestQueryResult Recursive
clickUri
required
string

The hyperlinkable item URI.

Notes:

  • Use the clickUri value when you want to create hyperlinks to the item, rather than the uri or printableUri value.
  • The clickUri value is not necessarily unique for each item.
excerpt
required
string

The contextual excerpt generated for the item (see the excerptLength query parameter).

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item excerpt string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

firstSentences
required
string or null

The first sentences retrieved from the item (see the retrieveFirstSentences query parameter).

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item firstSentences string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

flags
required
string

The flags that are set on the item by the index. Distinct values are separated by semicolons.

hasHtmlVersion
required
boolean

Whether the index contains an HTML version of this item.

hasMobileHtmlVersion
required
boolean

Whether the index contains a mobile HTML version of this item.

isRecommendation
required
boolean

Whether the item score was boosted as a Coveo ML recommendation.

isTopResult
required
boolean

Whether the item score was boosted by a featured result rule in the query pipeline.

isUserActionView
required
boolean

Whether the item score was boosted as a Coveo ML recommendation.

parentResult
required
object or null (RestQueryParentResult) Recursive
percentScore
required
number <double>

The item ranking score expressed as a percentage (see the sortCriteria and rankingFunctions query parameters).

printableUri
required
string

The human readable item URI.

Note: Avoid using the printableUri value to create hyperlinks to the item. Use the ClickUri value instead.

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item printableUri string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

rankingInfo
required
string

The raw debug information generated by the index to detail how the item was ranked. This property is null unless the debug query parameter is set to true.

rating
required
number <double>

The item rating (see the enableCollaborativeRating query parameter).

Note: Unless collaborative rating is enabled for your index, the value of this property is always 3.

required
object

The values of the fields which were retrieved for this item (see the fieldsToInclude and fieldsToExclude query parameters).

property name*
additional property
any
score
required
integer <int32>

The total ranking score computed for the item (see the sortCriteria and rankingFunctions query parameters).

summary
required
string or null

The item summary (see the summaryLength query parameter).

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item summary string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

title
required
string

The item title.

Note: When logging a Click usage analytics event for an opened query result item, the documentTitle field of that event should be set to the title value of the opened query result item.

required
Array of objects (RestHighlightResponse)

The length and offset of each word to highlight in the item title string.

Array
length
required
integer <int64>

The length (in number of characters) of the word to highlight.

offset
required
integer <int64>

The 0-based index position of the first character of the word to highlight in the string.

totalNumberOfChildResults
required
integer <int64>

The total number of children available in the index for this item, if result folding was applied (see the filterField query parameter).

uniqueId
required
string

The unique item identifier. You should consider the uniqueId value as an opaque string.

uri
required
string

The item URI.

Notes:

  • Avoid using the uri value to create hyperlinks to the item. Use the ClickUri value instead.
  • When logging a Click usage analytics event for an opened query result item, the documentUrl field of that event should be set to the uri value of the opened query result item.
ClickUri
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Excerpt
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

FirstSentences
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

PrintableUri
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

rankingModifier
string

If applicable, represents the type of ranking modification that was applied to this result.

Note: When logging a Click usage analytics event for an opened query result item, the rankingModifier field of that event should be set to the rankingModifier value of the opened query result item, if available.

Title
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

UniqueId
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

Uri
string
Deprecated

This property is deprecated; it should not be populated by Search API V2 searches.

searchUid
required
string

The query UUID. Each query sent to the Search API has its own randomly generated searchUid.

Note: When logging a Search or Custom usage analytics event for a query, or a Click usage analytics event for an opened query result item, the searchQueryUid field of that event should be set to the searchUid value of the query response.

required
Array of objects (RestSuggestedFacet)

A DNE facet suggestion.

Array
field
required
string

The name of the field on which the DNE facet suggestion is based.

Example: author

required
Array of objects (RestSuggestedFacetValue)

The name of the field on which the DNE facet suggestion is based.

Example: author

Array
value
required
string

A DNE facet value suggestion.

Example: Alice Smith

path
Array of strings

The path to the suggested facet value (only applies to hierarchical facet value suggestions).

Example: If the suggested hierarchical facet value is Parrot, the returned path could be ["Animals", "Birds", "Parrot"].

required
object

The terms to highlight in each query result item. Includes all basic query expression keywords, as well as any word stemmed from a basic query expression keyword (see the q query parameter), unless this keyword was preceded by the no stemming Coveo Cloud query syntax operator (+).

property name*
additional property
Array of strings
totalCount
required
integer <int32>

The total number of items matching the query for the current user (security trimming applied).

Note: When logging a Search usage analytics event for a query, the numberOfResults field of that event should be set to the totalCount value of the query (for reporting purposes).

totalCountFiltered
required
integer <int32>

The total number of items matching the query for the current user (security trimming applied) after duplicate filtering has been applied (see the duplicateFiltering query parameter).

required
Array of objects (RestTriggerResponse)

The actions to perform by the client based on the Trigger statements defined in query pipelines (see the pipeline query parameter).

Note:

A Trigger statement must have a condition. Otherwise, the Search API ignores it and does not include it in the triggers array of the query response (see Managing Query Pipeline Triggers).

Array
content
required
any
type
required
string
Enum: "notify" "execute" "query" "redirect"

The type of Coveo Cloud query pipeline Trigger statement (see Managing Query Pipeline Triggers).

errors
Array of strings

The errors that critically changed the query behaviour. These should be addressed right away to prevent future errors.

object (RestException)
code
required
string
context
string
object

Additional response attributes coming from the execution of query pipeline integrations.

Currently supported properties:

  • generativeQuestionAnsweringId: A stream ID to access the generated answer.
property name*
additional property
string
object

Automatically generated facets based on the generateAutomaticFacets request parameter.

Array of objects (RestFacetResult)
indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

isFallbackToAdmin
boolean

Whether the admin session ID was allowed and used by the Coveo for Salesforce search engine. The value will be set to true when it is the case, and might be absent or set to false otherwise.

object

Property returned when the queryCorrection feature is enabled.

It will either return:

  • The originalQuery and correctedQuery if the query was automatically corrected.
  • A list of corrections that could be be manually applied afterward.
correctedQuery
string

If the query was automatically corrected, this property indicates the corrected basic query expression (q) that was executed instead of the original one.

Array of objects (RestQueryCorrection)

If the query wasn't automatically corrected, this property contains the basic query expression (q) keyword corrections suggested by the Did You Mean index feature.

Array
correctedQuery
required
string

The resulting query expression correction suggestion.

required
Array of objects (RestWordCorrection)

The word correction suggestions.

Array
correctedWord
required
string

The suggested word correction.

length
required
integer <int32>

The length (in number of characters) of the corrected word.

offset
required
integer <int32>

The offset (in number of characters) of the corrected word, from the beginning of the resulting query expression correction suggestion.

originalWord
required
string

The original, un-corrected word.

originalQuery
string

If the query was automatically corrected, this property indicates the original basic query expression (q) that triggered the automatic query correction.

object (RestQuestionAnswer)
answerFound
required
boolean
answerSnippet
required
string
required
object (RestContentId)
contentIdKey
required
string
contentIdValue
required
string
question
required
string
required
Array of objects
Array
answerSnippet
required
string
required
object (RestContentId)
contentIdKey
required
string
contentIdValue
required
string
question
required
string
score
required
number
score
required
number
object
property name*
additional property
any
splitTestRun
string

Whether there is an active A/B test on the query pipeline. If not, this attribute will not appear in the response. It is used to identify and differentiate between A/B tests, and is crucial for tracking and analyzing the performance of different A/B test configurations.

warnings
Array of strings

The errors that did not make the query fail, but should be addressed. They might be security issues, deprecated behaviors, or any other kind of concern.

Request samples

Content type
application/json
{
  • "aq": "@year==2017",
  • "categoryFacets": [
    ],
  • "childField": "@foldingparent",
  • "commerce": {
    },
  • "cq": "@documenttype==forumpost",
  • "dictionaryFieldContext": {
    },
  • "disableQuerySyntax": false,
  • "dq": "@permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd",
  • "enableCollaborativeRating": false,
  • "enableDidYouMean": true,
  • "enableDuplicateFiltering": true,
  • "enableMLDidYouMean": true,
  • "enableQuerySyntax": true,
  • "excerptLength": 250,
  • "facetOptions": {
    },
  • "facets": [
    ],
  • "fieldsToExclude": [
    ],
  • "fieldsToInclude": [
    ],
  • "filterField": "@foldingcollection",
  • "filterFieldRange": 8,
  • "firstResult": 2,
  • "generateAutomaticFacets": {
    },
  • "groupBy": [
    ],
  • "lowercaseOperators": false,
  • "lq": "I am looking for an enterprise-class native cloud SaaS/PaaS solution that provides a unified and secure way to search for contextually relevant content across multiple enterprise systems.",
  • "lqPartialMatchKeywords": 4,
  • "lqPartialMatchMaxKeywords": 20,
  • "lqPartialMatchThreshold": "75%",
  • "mlDidYouMeanMaxCandidates": 5,
  • "mlDidYouMeanMinScore": 0.8,
  • "mlDidYouMeanUseFacetCount": true,
  • "numberOfResults": 5,
  • "parentField": "@foldingchild",
  • "partialMatch": true,
  • "partialMatchKeywords": 4,
  • "partialMatchThreshold": "75%",
  • "q": "Coveo \"Cloud V2\" platform",
  • "queryCorrection": {
    },
  • "queryFunctions": [
    ],
  • "questionMark": true,
  • "rankingFunctions": [
    ],
  • "retrieveFirstSentences": true,
  • "sortCriteria": "DateDescending",
  • "sortField": "string",
  • "staticQuery": true,
  • "summaryLength": 0,
  • "userActions": {
    },
  • "wildcards": true,
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
{
  • "apiVersion": 2,
  • "categoryFacets": [
    ],
  • "duration": 1235,
  • "errors": [
    ],
  • "exception": {
    },
  • "extendedResults": {
    },
  • "facets": [
    ],
  • "generateAutomaticFacets": {
    },
  • "groupByResults": [
    ],
  • "index": "mycoveocloudv2organizationid-cqjd206sta1xb9qyxfhhnsu294-Indexer-2-9rbfxhp1n07cth80ckzeh3zotc",
  • "indexDuration": 1175,
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "isFallbackToAdmin": true,
  • "phrasesToHighlight": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "queryCorrection": {
    },
  • "queryCorrections": [ ],
  • "questionAnswer": {
    },
  • "refinedKeywords": [
    ],
  • "requestDuration": 1181,
  • "results": [
    ],
  • "searchUid": "a0e4773c-39c3-423c-90cd-c03a640ecde5",
  • "splitTestRun": "CustomerQueryPipeline-mirror-1725560351",
  • "suggestedFacets": [
    ],
  • "termsToHighlight": {
    },
  • "totalCount": 250,
  • "totalCountFiltered": 245,
  • "triggers": [
    ],
  • "warnings": [
    ]
}

Get item data stream

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
contentType
string

The MIME type of the data stream to request.

Default: application/binary

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

dataStream
required
string

The name of the data stream to request.

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Get item in JSON format

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Response samples

Content type
application/json
{
  • "ClickUri": "string",
  • "Excerpt": "string",
  • "FirstSentences": "string",
  • "PrintableUri": "string",
  • "Title": "string",
  • "UniqueId": "string",
  • "Uri": "string",
  • "absentTerms": [
    ],
  • "childResults": [
    ],
  • "excerpt": "... the new Coveo Cloud V2 and Coveo Cloud V1 ... the main differences between the two Coveo Cloud versions ...",
  • "excerptHighlights": [
    ],
  • "firstSentences": "Hello, I know Coveo currently hosts organizations in two independent cloud platforms, the new Coveo Cloud V2 and Coveo Cloud V1, the original Coveo offering in the cloud. I would like to learn the main differences between the two Coveo Cloud versions ...",
  • "firstSentencesHighlights": [
    ],
  • "flags": "HasHtmlVersion;HasMobileHtmlVersion",
  • "hasHtmlVersion": true,
  • "hasMobileHtmlVersion": true,
  • "isRecommendation": false,
  • "isTopResult": false,
  • "isUserActionView": false,
  • "parentResult": { },
  • "percentScore": 90.73539,
  • "printableUriHighlights": [
    ],
  • "rankingInfo": "Document weights:\nTitle: 0; Quality: 180; Date: 596; Adjacency: 0; Source: 500; Custom: 350; Collaborative rating: 0; QRE: 0; Ranking functions: 0;\n\nTotal weight: 1626",
  • "rankingModifier": "TopResult",
  • "rating": 3,
  • "raw": {
    },
  • "score": 1626,
  • "summary": "string",
  • "summaryHighlights": [
    ],
  • "title": "Differences between Coveo Cloud V2 and V1",
  • "titleHighlights": [
    ],
  • "totalNumberOfChildResults": 0,
  • "uniqueId": "84.72597$https://example.com/Root:0/Topic:898/Post:2",
}

List available query extensions

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Send facet search request

Executes a facet search request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
field
required
string

The name of the field against which to execute the facet search request.

basePath
Array of strings

The shared base path for all values in the facet to search against.

If a basePath is specified, the search request will be executed against hierarchical values that begin with that base path only (i.e., other hierarchical values will be filtered out).

object

A dictionary that maps index field values to facet value display names.

Note:

When specifying display captions for hierarchical facet values, you can use full values (e.g., all;electronics;laptops), and/or for "leaf" values (e.g., laptops) as keys. If both are provided, the full value takes priority.

Examples:

  • Specific (i.e., scalar) facet values: {\"#FF8000\": \"Orange\", \"#8000FF\": \"Purple\"}
  • Hierarchical facet values:** `{"all;electronics;laptops": "Laptops", "smartphones": "Smart Phones"} "
delimitingCharacter
string

The character to use to split field values into a hierarchical sequence.

Example:

For a multi-value field containing the following values:

c; c>folder2; c>folder2>folder3;

The delimiting character is >.

For a hierarchical field containing the following values: c;folder2;folder3;

The delimiting character is ;.

Default: ;

filterFacetCount
boolean

Whether to exclude folded result parents when estimating the result count for each facet value.

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: false

ignorePaths
Array of strings[ items ]

A list of paths to filter out from the hierarchical facet search results.

numberOfValues
integer <int32>
Default: 10

The maximum number of values to fetch.

**Default: 10

query
string

The string to match.

Note: Typically, this should be set to the text entered by the end-user in the facet search box, to which one or more wildcard characters (*) may be added.

object (RestQueryParameters)
type
string

The kind of facet against which the search request is being made.

Allowed values:

  • specific
  • hierarchical

Default: specific

Responses

Request samples

Content type
application/json
Example
{
  • "basePath": [
    ],
  • "captions": {
    },
  • "delimitingCharacter": "string",
  • "field": "color",
  • "filterFacetCount": [
    ],
  • "ignorePaths": [
    ],
  • "numberOfValues": 10,
  • "query": "*oran*",
  • "searchContext": {
    },
  • "type": "hierarchical"
}

Response samples

Content type
application/json
{
  • "moreValuesAvailable": true,
  • "values": [
    ]
}

List all fields

Gets all fields in the target Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Response samples

Content type
application/json
{
  • "fields": [
    ]
}

Find fields from results of a query expression

Find fields name from results matching the q expression.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"VIEW_ALL_CONTENT","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json

The query to get the fields from.

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

q
string
Default: ""

The basic query expression, typically the keywords entered by the end user in a query box.

Responses

Request samples

Content type
application/json
{
  • "dictionaryFieldContext": {
    },
  • "q": "Coveo \"Cloud V2\" platform"
}

Response samples

Content type
application/json
{
  • "fields": [
    ]
}

Get HTML item preview

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
Array of objects (ActionHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object (RestCommerceParameters)

The parameters for Coveo for Commerce.

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

dictionaryFieldContext
object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This cannot be used at the same time as fieldAliases.

Note: This parameter will be overridden if the search request is authenticated by a search token that enforces a specific dictionaryFieldContext.

disableQuerySyntax
boolean
Deprecated

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string

The disjunction query expression, typically populated by Coveo ML automatic relevance tuning models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableNavigation
boolean
enableQuerySyntax
boolean

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)

The global configuration options that apply to all facet requests performed along with the query (see the facets query parameter).

Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes:

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes:

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

findNext
integer <int32>
findPrevious
integer <int32>
firstResult
integer <int32>

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

isGuestUser
boolean

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

language
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default: 100

lqPartialMatchThreshold
string

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer <int32>

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer <int32>

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32>
parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

q
string

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

requestedOutputSize
integer <int32>

The approximate number of bytes to request in the HTML response. Default: 0, meaning that the entire HTML document is requested.

retrieveFirstSentences
boolean

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria which will be applied sequentially, i.e., if there's a tie on the 1st criterion, the API uses the 2nd criterion to break the tie. However, this only works when combining:

  • a relevancy criterion followed by one or more field or date criteria.
  • a qre criterion followed by one or more field or date criteria.
  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criterion and one or more field criteria in any order (e.g., @views descending, date ascending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

object (RestUserActionParameter)

The parameters allowing user actions to be retrieved in query results.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

visitorId
string
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Get HTML item preview

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
enableNavigation
boolean
findNext
integer <int32>
findPrevious
integer <int32>
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32>
requestedOutputSize
integer <int32>

The approximate number of bytes to request in the HTML response. Default: 0, meaning that the entire HTML document is requested.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string (AQ)

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string (CQ)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

disableQuerySyntax
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string (DQ)

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean
Default: false

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean
Default: false

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean
Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean
Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean
Default: true

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>
Default: 200

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)
Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>
Default: 5

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>
Default: 0

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

object

Generate facets based on the most relevant fields in the index.

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean
Default: false

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string (LQ)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer <int32>
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

lqPartialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>
Default: 3

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>
Default: 1

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean
Default: false

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0
Default: 10

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean
Default: false

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string (Q)

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

object

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

  • Attempt to correct your query if it doesn't return enough results.
  • If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

  • The original query
  • The corrected query

Otherwise, it will return:

  • A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean
Default: false

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string
Default: "Relevancy"

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean
Default: false

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>
Default: 0

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)
visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean
Default: false

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Request samples

Content type
application/json
{
  • "aq": "@year==2017",
  • "categoryFacets": [
    ],
  • "childField": "@foldingparent",
  • "commerce": {
    },
  • "cq": "@documenttype==forumpost",
  • "dictionaryFieldContext": {
    },
  • "disableQuerySyntax": false,
  • "dq": "@permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd",
  • "enableCollaborativeRating": false,
  • "enableDidYouMean": true,
  • "enableDuplicateFiltering": true,
  • "enableMLDidYouMean": true,
  • "enableQuerySyntax": true,
  • "excerptLength": 250,
  • "facetOptions": {
    },
  • "facets": [
    ],
  • "fieldsToExclude": [
    ],
  • "fieldsToInclude": [
    ],
  • "filterField": "@foldingcollection",
  • "filterFieldRange": 8,
  • "firstResult": 2,
  • "generateAutomaticFacets": {
    },
  • "groupBy": [
    ],
  • "lowercaseOperators": false,
  • "lq": "I am looking for an enterprise-class native cloud SaaS/PaaS solution that provides a unified and secure way to search for contextually relevant content across multiple enterprise systems.",
  • "lqPartialMatchKeywords": 4,
  • "lqPartialMatchMaxKeywords": 20,
  • "lqPartialMatchThreshold": "75%",
  • "mlDidYouMeanMaxCandidates": 5,
  • "mlDidYouMeanMinScore": 0.8,
  • "mlDidYouMeanUseFacetCount": true,
  • "numberOfResults": 5,
  • "parentField": "@foldingchild",
  • "partialMatch": true,
  • "partialMatchKeywords": 4,
  • "partialMatchThreshold": "75%",
  • "q": "Coveo \"Cloud V2\" platform",
  • "queryCorrection": {
    },
  • "queryFunctions": [
    ],
  • "questionMark": true,
  • "rankingFunctions": [
    ],
  • "retrieveFirstSentences": true,
  • "sortCriteria": "DateDescending",
  • "sortField": "string",
  • "staticQuery": true,
  • "summaryLength": 0,
  • "userActions": {
    },
  • "wildcards": true,
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Log in to authentication provider

Directs the browser to URI of the target Search API authentication provider, and back to the origin search page once the authentication process is complete. This authentication provider must be properly configured in the Coveo Cloud organization.

Privilege(s) required

Authorizations:
oauth2
path Parameters
provider
required
string

The name of the Search API authentication provider to log in to.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Log in to authentication provider

Directs the browser to URI of the target Search API authentication provider, and back to the origin search page once the authentication process is complete. This authentication provider must be properly configured in the Coveo Cloud organization.

Privilege(s) required

Authorizations:
oauth2
path Parameters
provider
required
string
Example: My SharePoint Server

The name of the Search API authentication provider to log in to.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Plan search execution

See Performing a Query.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
Array of objects (ActionHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object (RestCommerceParameters)

The parameters for Coveo for Commerce.

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

dictionaryFieldContext
object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This cannot be used at the same time as fieldAliases.

Note: This parameter will be overridden if the search request is authenticated by a search token that enforces a specific dictionaryFieldContext.

disableQuerySyntax
boolean
Deprecated

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string

The disjunction query expression, typically populated by Coveo ML automatic relevance tuning models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)

The global configuration options that apply to all facet requests performed along with the query (see the facets query parameter).

Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes:

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes:

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

isGuestUser
boolean

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

language
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default: 100

lqPartialMatchThreshold
string

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer <int32>

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer <int32>

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

q
string

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria which will be applied sequentially, i.e., if there's a tie on the 1st criterion, the API uses the 2nd criterion to break the tie. However, this only works when combining:

  • a relevancy criterion followed by one or more field or date criteria.
  • a qre criterion followed by one or more field or date criteria.
  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criterion and one or more field criteria in any order (e.g., @views descending, date ascending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)

The parameters allowing user actions to be retrieved in query results.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

visitorId
string
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Response samples

Content type
application/json
{
  • "parsedInput": {
    },
  • "preprocessingOutput": {
    }
}

Plan search execution

See Performing a Query.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
aq
string (AQ)

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Array of objects (RestCategoryFacetRequest)

Data to easily query a hierarchical field using a path of hierarchical values.

childField
string

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
object
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

cq
string (CQ)

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

  • Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
  • Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.
debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

disableQuerySyntax
boolean
Deprecated
Default: false

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

dq
string (DQ)

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

enableCollaborativeRating
boolean
Default: false

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

enableDidYouMean
boolean
Default: false

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
  • The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

enableDuplicateFiltering
boolean
Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

  • Two items must be at least 85% similar to one another to be considered duplicates.
  • When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
  • Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.
  • Duplicate filtering and result folding are mutually exclusive.

Default: false

enableMLDidYouMean
boolean
Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

  • The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
  • When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

enableQuerySyntax
boolean
Default: true

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

excerptLength
integer <int32>
Default: 200

The maximum length of result excerpts (in number of characters).

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

object or null (RestFacetOptions)
Array of any (RestFacetRequest)

The facet operations to perform on the query results.

fieldsToExclude
Array of strings

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

fieldsToInclude
Array of strings

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

filterField
string

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
filterFieldRange
integer <int32>
Default: 5

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Notes::

  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

Default: 5

firstResult
integer <int32>
Default: 0

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

object

Generate facets based on the most relevant fields in the index.

Array of objects (RestGroupBy)

The Group By operations to perform on the query results, typically to extract facets.

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lowercaseOperators
boolean
Default: false

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

lq
string (LQ)

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

lqPartialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

lqPartialMatchMaxKeywords
integer <int32>
Default: 100

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

lqPartialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string (""), or
  • the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlDidYouMeanMaxCandidates
integer <int32>
Default: 3

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

mlDidYouMeanMinScore
number <double>
Default: 1

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

mlDidYouMeanUseFacetCount
boolean
Default: false

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
numberOfResults
integer <int32> >= 0
Default: 10

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value is 2,000 items.

Default: 10

parentField
string

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

  • In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
  • The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).
  • Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.
partialMatch
boolean
Default: false

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

  • This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
  • When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

partialMatchKeywords
integer <int32>
Default: 5

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • Repeated keywords in a basic expression count as a single keyword.
  • Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
  • Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

partialMatchThreshold
string
Default: "50%"

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

  • a 32-bits unsigned integer (e.g., 3),
  • a percentage value between 0% and 100% (e.g., 75%),
  • the empty string, or
  • the all string.

The "" and the all value are both equivalent to 100%.

Notes:

  • This parameter has no meaning unless the partialMatch parameter is set to true.
  • A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

  • 3
  • 75%
  • all

Default: 50%

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string (Q)

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

object

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

  • Attempt to correct your query if it doesn't return enough results.
  • If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

  • The original query
  • The corrected query

Otherwise, it will return:

  • A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

Array of objects (RestQueryFunction)

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

questionMark
boolean
Default: false

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

Array of objects (RestRankingFunction)

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

retrieveFirstSentences
boolean
Default: false

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string
Default: "Relevancy"

The criteria to use for sorting the query results.

Allowed values:

  • relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
  • qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
  • nosort: do not sort the query results; the index will return result items in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

  • two or more field criteria (e.g., @views descending,@likes descending).
  • a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

  • date ascending
  • @author ascending
  • date descending,@views descending,@likes descending

Default: relevancy

sortField
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

staticQuery
boolean
Default: false

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

summaryLength
integer <int32>
Default: 0

The length of the automatically generated item summary.

The Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

This summary is generated independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

object (RestUserActionParameter)
visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

wildcards
boolean
Default: false

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

Responses

Request samples

Content type
application/json
{
  • "aq": "@year==2017",
  • "categoryFacets": [
    ],
  • "childField": "@foldingparent",
  • "commerce": {
    },
  • "cq": "@documenttype==forumpost",
  • "dictionaryFieldContext": {
    },
  • "disableQuerySyntax": false,
  • "dq": "@permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd",
  • "enableCollaborativeRating": false,
  • "enableDidYouMean": true,
  • "enableDuplicateFiltering": true,
  • "enableMLDidYouMean": true,
  • "enableQuerySyntax": true,
  • "excerptLength": 250,
  • "facetOptions": {
    },
  • "facets": [
    ],
  • "fieldsToExclude": [
    ],
  • "fieldsToInclude": [
    ],
  • "filterField": "@foldingcollection",
  • "filterFieldRange": 8,
  • "firstResult": 2,
  • "generateAutomaticFacets": {
    },
  • "groupBy": [
    ],
  • "lowercaseOperators": false,
  • "lq": "I am looking for an enterprise-class native cloud SaaS/PaaS solution that provides a unified and secure way to search for contextually relevant content across multiple enterprise systems.",
  • "lqPartialMatchKeywords": 4,
  • "lqPartialMatchMaxKeywords": 20,
  • "lqPartialMatchThreshold": "75%",
  • "mlDidYouMeanMaxCandidates": 5,
  • "mlDidYouMeanMinScore": 0.8,
  • "mlDidYouMeanUseFacetCount": true,
  • "numberOfResults": 5,
  • "parentField": "@foldingchild",
  • "partialMatch": true,
  • "partialMatchKeywords": 4,
  • "partialMatchThreshold": "75%",
  • "q": "Coveo \"Cloud V2\" platform",
  • "queryCorrection": {
    },
  • "queryFunctions": [
    ],
  • "questionMark": true,
  • "rankingFunctions": [
    ],
  • "retrieveFirstSentences": true,
  • "sortCriteria": "DateDescending",
  • "sortField": "string",
  • "staticQuery": true,
  • "summaryLength": 0,
  • "userActions": {
    },
  • "wildcards": true,
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "parsedInput": {
    },
  • "preprocessingOutput": {
    }
}

Request query suggestions

See Getting Query Suggestions.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
Array of objects (ActionHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

additionalData
object
Deprecated

This parameter is exposed for backward compatibility reasons.

object or null (AnalyticsRequestParameters)
autoCompleter
string
Deprecated

This parameter is exposed for backward compatibility reasons.

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

count
integer <int32>

The desired number of query suggestions.

debug
boolean

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

enableWordCompletion
boolean

Whether to attempt to complete the last word of the current basic query expression (see the q parameter) and boost the ranking score of the resulting expression so that it is returned as the first query suggestion.

format
string

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

isGuestUser
boolean

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

language
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

maximumAge
integer <int32>

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer <int32>

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

q
string
Example: q=Coveo "Cloud V2" platform

The basic query expression, typically the keywords entered by the end user in a query box.

recommendation
string

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Response samples

Content type
application/json
{
  • "completions": [
    ],
  • "responseId": "e1a4c9dd-71d2-4e68-9589-11bc3e640da0"
}

Request query suggestions

See Getting Query Suggestions.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
autoCompleter
string
Deprecated

This parameter is exposed for backward compatibility reasons.

object (RestCommerceParameters)
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

count
integer <int32>

The desired number of query suggestions.

debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

enableWordCompletion
boolean

Whether to attempt to complete the last word of the current basic query expression (see the q parameter) and boost the ranking score of the resulting expression so that it is returned as the first query suggestion.

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

q
string

The basic query expression, typically the keywords entered by the end user in a query box.

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Request samples

Content type
application/json
{
  • "autoCompleter": "string",
  • "count": 0,
  • "enableWordCompletion": true,
  • "q": "Coveo \"Cloud V2\" platform",
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "commerce": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "completions": [
    ],
  • "responseId": "e1a4c9dd-71d2-4e68-9589-11bc3e640da0"
}

Update user rating Deprecated

The Coveo Cloud V2 platform does not support collaborative rating. Therefore, this operation is obsolete in Coveo Cloud V2.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

rating
required
string

The rate to be updated.

uniqueId
required
string

The unique ID of the document.

Responses

Get item in text format

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

uniqueId
required
string

The unique ID of the document.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Responses

Create search token

Creates a temporary JSON web token which can be used to impersonate one or several security identities when authenticating a query (see Search Token Authentication).

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"IMPERSONATE_SEARCH_API","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The search token information.

required
Array of objects (RestUserId)

The security identities to impersonate when authenticating a query with this search token.

canSeeUserProfileOf
Array of strings

The username and/or visitorId values whose corresponding usage analytics-recorded user profiles can be accessed using the search token.

Note: This property is meant to be used when generating search tokens for users requiring contextual information about other users to improve search relevance (e.g., support agents using an insight panel).

object (CommerceParameters)
dictionaryFieldContext
object

The dictionary field context to enforce when authenticating a query with this search token. This value will override the dictionaryFieldContext parameter of the query itself.

A dictionary field context is a key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

For example, suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } when creating a search token means that, for any query made with that search token, any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This cannot be used at the same time as allowedDictionaryFieldKeys.

filter
string

The filter query expression to apply when authenticating a query with this search token.

This expression will be merged with the constant part of the query expression (cq) using an AND operator.

The filter can also be used in query pipeline condition statements (e.g., when $constantQuery contains \"@source==KnowledgeBase\").

licenseDefinitionKey
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

pipeline
string

The name of the query pipeline to use when authenticating a query with this search token.

This query pipeline will take precedence over the possible output of all other query pipeline routing mechanisms when using this search token (see Query Pipeline Routing Mechanisms and Rules).

salesforceCommunityUrl
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

salesforceFallbackToAdmin
boolean

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

salesforceOrganizationId
string

Internal: The ID of Salesforce organization, used to differentiate Salesforce organizations linked to the same Coveo organization.

salesforceUser
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

scope
integer <int32>
Deprecated

This property is exposed for backward compatibility reasons only.

searchHub
string

The name of the search hub to enforce when authenticating a query with this search token.

This value will override the searchhub parameter of the query itself, and will be passed as the originLevel1 property value when logging usage analytics search events.

The search hub can also be used in query pipeline condition statements (e.g., when $searchhub is \"CommunityHub\").

superUserToken
string
Deprecated

This property is exposed for backward compatibility reasons only.

userDisplayName
string

The userDisplayName to pass when logging usage analytics search events.

This information is leveraged in the Analytics section of the Coveo Cloud administration console.

userGroups
Array of strings

The userGroups to pass when logging usage analytics search events.

This information is leveraged in the Analytics section of the Coveo Cloud administration console.

User groups can be also be used in query pipeline condition statements (e.g., when $groups contains \"Employees\").

usertype
string

Internal: This property is exposed for internal use by the Coveo for Salesforce integration.

validFor
integer <int32>
Default: 86400000

The number of milliseconds the search token will remain valid for once it has been created.

Minimum value: 900000 (i.e., 15 minutes)

Maximum/default: 86400000 (i.e., 24 hours)

Responses

Request samples

Content type
application/json
{
  • "canSeeUserProfileOf": [
    ],
  • "commerce": {
    },
  • "dictionaryFieldContext": { },
  • "filter": "@source==KnowledgeBase",
  • "licenseDefinitionKey": "string",
  • "pipeline": "InternalSearch",
  • "salesforceCommunityUrl": "string",
  • "salesforceFallbackToAdmin": true,
  • "salesforceOrganizationId": "00Df23090018W5bEAG",
  • "salesforceUser": "string",
  • "scope": 0,
  • "searchHub": "SupportHub",
  • "superUserToken": "string",
  • "userDisplayName": "Alice Smith",
  • "userGroups": [
    ],
  • "userIds": [
    ],
  • "usertype": "string",
  • "validFor": 3600000
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Get values for one field

Lists all values of the target field.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
Array of objects (ActionHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
object (RestCommerceParameters)

The parameters for Coveo for Commerce.

constantQueryOverride
string

A different constant query expression (cq) to use.

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

debug
boolean

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

dictionaryFieldContext
object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This cannot be used at the same time as fieldAliases.

Note: This parameter will be overridden if the search request is authenticated by a search token that enforces a specific dictionaryFieldContext.

disjunctionQueryOverride
string

A different disjunction query expression (dq) to use.

field
required
string

The name of the field from which to retrieve values.

format
string

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

ignoreAccents
boolean

Whether to treat accentuated characters as non-accentuated characters when retrieving field values (e.g., treat é, è, ê, etc., as e).

Default: true

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

isGuestUser
boolean

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

language
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lookupField
string
Deprecated

This parameter is exposed for backward compatibility reasons.

The name of an additional field from which to retrieve values.

maximumAge
integer <int32>

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumNumberOfValues
integer <int32> >= 0

The maximum number of field values to return.

Default: 10

maximumTimeoutMs
integer <int32>

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pattern
string

The pattern that the field values must match.

See also the patternType parameter."

patternType
string

The type of pattern that is being used to list field values.

Use:

  • wildcard to parse the specified pattern as a wildcard expression.
  • regularexpression to parse the specified pattern as a regular expression.
  • editdistance to apply the Edit Distance algorithm to match values that are close to the specified pattern.
  • phonetic to apply a phonetic algorithm to match values that are phonetically similar to the specified pattern.

Default: wildcard

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

queryOverride
string

A different basic query expression (q) use.

recommendation
string

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string

The sort criteria to use.

Use:

  • occurrences to sort by number of occurrences, with field values having the highest number of occurrences appearing first.
  • nosort to avoid sorting the results of the Group By operation. The field values will appear in an unspecified order.

Default: occurrences

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

visitorId
string
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get values for one field

Lists all values of the target field.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
field
required
string

The name of the field from which to retrieve values.

Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
object (RestCommerceParameters)
constantQueryOverride
string

A different constant query expression (cq) to use.

object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

dictionaryFieldContext
object

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

Note: This parameter will be overridden if the request is authenticated by a search token that enforces a specific dictionaryFieldContext.

disjunctionQueryOverride
string

A different disjunction query expression (dq) to use.

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

ignoreAccents
boolean

Whether to treat accentuated characters as non-accentuated characters when retrieving field values (e.g., treat é, è, ê, etc., as e).

Default: true

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

lookupField
string
Deprecated

This parameter is exposed for backward compatibility reasons.

The name of an additional field from which to retrieve values.

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumNumberOfValues
integer <int32> >= 0

The maximum number of field values to return.

Default: 10

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
pattern
string

The pattern that the field values must match.

See also the patternType parameter."

patternType
string

The type of pattern that is being used to list field values.

Use:

  • wildcard to parse the specified pattern as a wildcard expression.
  • regularexpression to parse the specified pattern as a regular expression.
  • editdistance to apply the Edit Distance algorithm to match values that are close to the specified pattern.
  • phonetic to apply a phonetic algorithm to match values that are phonetically similar to the specified pattern.

Default: wildcard

pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

queryOverride
string

A different basic query expression (q) use.

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

sortCriteria
string or null

The sort criteria to use.

Use:

  • occurrences to sort by number of occurrences, with field values having the highest number of occurrences appearing first.
  • nosort to avoid sorting the results of the Group By operation. The field values will appear in an unspecified order.

Default: occurrences

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Request samples

Content type
application/json
{
  • "constantQueryOverride": "string",
  • "dictionaryFieldContext": { },
  • "disjunctionQueryOverride": "string",
  • "field": "@author",
  • "ignoreAccents": true,
  • "lookupField": "string",
  • "maximumNumberOfValues": 0,
  • "pattern": "string",
  • "patternType": "string",
  • "queryOverride": "string",
  • "sortCriteria": "string",
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "commerce": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get values for several field

Lists all values of the target field.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
Array of objects (ActionHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
required
Array of objects (RestListFieldValuesBatchParameter)

An array of parameters to retrieve field values.

context
object

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

debug
boolean

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

format
string

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

index
string

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

isGuestUser
boolean

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

language
string
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

maximumAge
integer <int32>

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer <int32>

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

pipeline
string

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.
  • When using this parameter to list field values, not all query pipeline rules are supported. The only supported ones are stop, thesaurus and queryParamOverride.

See also Managing Query Pipelines.

recommendation
string

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

  See also the `searchHub` parameter.
timezone
string

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

visitorId
string
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Response samples

Content type
application/json
{
  • "batch": [
    ]
}

Get values for several field

Lists all values of the target field.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
object or null (AnalyticsRequestParameters)
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
required
Array of objects (RestListFieldValuesParameter)

An array of parameters to retrieve field values.

Array of objects or null (ActionsHistory)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

object or null (AnalyticsRequestParameters)
object (RestCommerceParameters)
object or null (Context)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

debug
boolean or null (Debug)
Default: false

Whether to force a successful response to include debug information.

Notes:

  • Debug information can only appear in responses in the JSON format (see the format parameter).
  • Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

format
string or null (Format)
Default: "json"

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

index
string or null (Index)

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexToken
string or null (IndexToken)

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

indexType
string or null (IndexType)
Default: "coveo"

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

language
string or null (Language)
Deprecated

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

locale
string or null (Locale)

The locale of the current user. Must comply with IETF's BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

logicalIndex
string or null (LogicalIndex)
Default: "default"

The identifier for a logical group of indexes that have been configured to include documents from the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

maximumAge
integer or null <int32> (MaximumAge)
Default: -1

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

maximumTimeoutMs
integer or null <int32> (MaximumTimeoutMs)
Default: 0

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

mlParameters
object or null (MlParameters)

A map of options to pass to the Coveo ML models associated with the request's target query pipeline.

Available parameters:

  • considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to ER models only. Default is true.
  • maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to ER models only. By default, all actionsHistory items are considered.
  • num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, ER, and QS models. Default depends on model configuration.
  • padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to ER models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
  • wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
  • minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
  • itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
  • itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
  • categoryFilter (string): The name of a category of products to get recommendations for.
  • brandFilter (string): The name of a brand of products to get recommendations for.
  • filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to ART, QS, and DNE models that don't use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

  • {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
  • {"wordSelection": "wordsKept:4"}
pipeline
string or null (Pipeline)

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

object or null (PipelineRuleParameters) <= 255 properties

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

  • {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
  • {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

recommendation
string or null (Recommendation)

The identifier of the recommendation interface from which the request originates (see CoveoRecommendation).

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

referrer
string or null (Referrer)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

searchHub
string or null (SearchHub)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

tab
string or null (Tab)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

timezone
string or null (Timezone)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

visitorId
string or null (VisitorId)
Deprecated

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Responses

Request samples

Content type
application/json
{
  • "batch": [
    ],
  • "actionsHistory": [
    ],
  • "analytics": {
    },
  • "commerce": {
    },
  • "context": { },
  • "debug": false,
  • "format": "json",
  • "index": "myorg-nvoqun-Indexer1-pbi2nbuw",
  • "indexToken": "ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==",
  • "indexType": "coveo",
  • "language": "string",
  • "locale": "en-US",
  • "logicalIndex": "webcontentonly",
  • "maximumAge": 1800000,
  • "maximumTimeoutMs": 15000,
  • "mlParameters": {
    },
  • "pipeline": "CustomerQueryPipeline",
  • "pipelineRuleParameters": {
    },
  • "recommendation": "Recommendation",
  • "searchHub": "CustomerPortal",
  • "tab": "ForumTab",
  • "timezone": "America/New_York",
  • "visitorId": "5cb98953-9c13-42ff-8176-e6fcba6a50bf"
}

Response samples

Content type
application/json
{
  • "batch": [
    ]
}

Statements

List query pipeline statements

Gets a sorted page of query pipeline statements matching certain criteria from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

subFeature
Array of strings (SubFeature)
Items Enum: "queryParamOverride" "querySuggestParamOverride"

The query pipeline sub-feature to match.

Allowed values:

  • Parameter overrides: queryParamOverride and querySuggestParamOverride.

By default, results are not required to match a specific query pipeline sub-feature.

Responses

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Create query pipeline statement

Creates a new query pipeline statement in a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The query pipeline statement information.

definition
required
string

The query pipeline language expression that defines this statement (see Query Pipeline Language (QPL)).

feature
required
string
Enum: "filter" "trigger" "ranking" "stop" "thesaurus" … 6 more

The query pipeline feature expressed by this statement (see Query Pipeline Language (QPL)).

description
string

The intended purpose of this statement in an actual implementation.

id
string

The unique identifier of this statement.

parent
string

The unique identifier of the condition that must be met for this statement to apply.

Responses

Request samples

Content type
application/json
{
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "feature": "ranking",
  • "id": "string",
  • "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": {
    },
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "detailed": null,
  • "displayName": "",
  • "feature": "ranking",
  • "id": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": {
    },
  • "position": 2,
  • "ready": false,
  • "statementGroupId": "string",
  • "warnings": [
    ]
}

Bulk delete query pipeline statements

Delete multiple statements at once for a specific pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The statements to delete

ids
required
Array of strings <= 100 items [ items <= 38 characters ]

A list of resource identifiers to delete. A maximum of 100 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

List query pipeline statements

Gets a sorted page of query pipeline statements matching certain criteria from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Copy query pipeline statements

Copies specific statements from an origin to a target query pipeline. Using the same pipeline as origin and target will duplicate the specified statements in that pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The copy operation to perform.

destinationPipelineId
required
string

The unique identifier of the query pipeline to copy the statements to.

statementIds
required
Array of strings

The unique identifiers of the query pipeline statements to copy.

Responses

Request samples

Content type
application/json
{
  • "destinationPipelineId": "120deecf-7822-4d7b-885f-53f184a3a76",
  • "statementIds": [
    ]
}

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Export query pipeline statements

Exports the definition, condition, and description of statements from a specific query pipeline to a CSV file.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Import query pipeline statements

Import the definition, condition, and description of statements from a CSV file to a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: multipart/form-data
fileName
required
string <binary>

Responses

Response samples

Content type
application/json
"string"

Validate a single statement operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains an operation to validate.

required
object (RestOperationValidationRequestIncomingStatement)
operationType
required
string (ValidationOperationType)
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingStatement)
resourceId
string

The identifier of the resource when operationType is UPDATE or DELETE.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate a batch of statement operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (RestOperationValidationRequestIncomingStatement)

A list of operations to validate.

Array
operationType
required
string (ValidationOperationType)
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingStatement)
resourceId
string

The identifier of the resource when operationType is UPDATE or DELETE.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete query pipeline statement

Deletes a single query pipeline statement from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
"string"

Get query pipeline statement

Gets a single query pipeline statement from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": {
    },
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "detailed": null,
  • "displayName": "",
  • "feature": "ranking",
  • "id": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": {
    },
  • "position": 2,
  • "ready": false,
  • "statementGroupId": "string",
  • "warnings": [
    ]
}

Update query pipeline statement

Updates a single query pipeline statement in a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The updated query pipeline statement information.

definition
required
string

The query pipeline language expression that defines this statement (see Query Pipeline Language (QPL)).

feature
required
string
Enum: "filter" "trigger" "ranking" "stop" "thesaurus" … 6 more

The query pipeline feature expressed by this statement (see Query Pipeline Language (QPL)).

description
string

The intended purpose of this statement in an actual implementation.

id
string

The unique identifier of this statement.

parent
string

The unique identifier of the condition that must be met for this statement to apply.

Responses

Request samples

Content type
application/json
{
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "feature": "ranking",
  • "id": "string",
  • "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": {
    },
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "detailed": null,
  • "displayName": "",
  • "feature": "ranking",
  • "id": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": {
    },
  • "position": 2,
  • "ready": false,
  • "statementGroupId": "string",
  • "warnings": [
    ]
}

Move query pipeline statement

Sets the position of a query pipeline statement in a specific query pipeline and updates other statement positions as appropriate.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The move operation to perform.

after
string

The unique identifier of the statement after which to move this statement in the target query pipeline.

Use either this property or the position property (not both) to move this statement.

pageSize
integer <int32>
Deprecated

This parameter is exposed for backward compatibility reasons only.

position
integer <int32>

The 1-based position of this statement relative to other statements in the target query pipeline.

Use either this property or the after property (not both) to move this statement.

Responses

Request samples

Content type
application/json
{
  • "after": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "pageSize": 0,
  • "position": 0
}

Response samples

Content type
application/json
[
  • {
    }
]

Result rankings

Get a list of result ranking rules

Get a list of result ranking rules

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
associatedGroups
Array of strings or null

The group names to allow in the results. Include the null value in the array to allow rules that are not associated with any groups (e.g., [null, "mygroup"]). If you leave this parameter undefined, all groups will be allowed in the results. If you pass an empty array ([]), no rules will be returned.

enabledStatus
boolean
Deprecated

The enabled status of result ranking rules to allow in the returned list.

Set to true to only allow rules whose enabled property is set to true, and vice versa.

By default, both enabled and disabled rules are allowed.

Deprecated: Use ruleStatuses instead.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

kind
string
Deprecated

The kind of result ranking rules to allow in the returned list (i.e., featured_result or ranking_expression).

By default, both kinds of rules are allowed.

Deprecated: Use ruleTypes instead.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

ruleStatuses
Array of strings (ResultRankingRuleStatus)
Default: "active&ruleStatuses=inactive"
Items Enum: "active" "inactive"

The rule status to allow in the results. Available statuses are: "active", "inactive".

If you leave this parameter undefined, all rule statuses will be allowed in the results. If you pass an empty array ([]), no rules will be returned.'

ruleTypes
Array of strings (ResultRankingRuleType)
Default: "featuredResults&ruleTypes=rankingExpressions"
Items Enum: "featuredResults" "rankingExpressions"

The rule types to allow in the results. Available types are "featuredResults", "rankingExpressions". If you leave this parameter undefined, all rule types will be allowed in the results. If you pass an empty array ([]), no rules will be returned."

statementGroupId
string

The unique identifier of the statement group.

Responses

Response samples

Content type
application/json
{
  • "groupedBy": {
    },
  • "resultRankings": [
    ],
  • "totalCount": 0,
  • "totalPages": 0
}

Create a new result ranking rule

Create a new result ranking rule

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The new result ranking to create

kind
required
string

The kind of result ranking.

name
required
string

The name of the result ranking.

required
Array of ResultRankingRuleTargetUniqueId (object) or ResultRankingRuleTargetLocalizedContent (object) or ResultRankingRuleTargetQueryExpression (object) (ResultRankingRuleTargetFeaturedResults)

Documents that will show up when conditions and predicates are met.

object (ResultRankingRuleCondition)
object (PredicateMatchOperator)
description
string

The intended purpose of this result ranking.

enabled
boolean
Default: true

Whether this result ranking should be used by the query pipeline.

includeInFacets
boolean
Default: true
matchAdvancedQuery
boolean
Default: true

When set to true, a featured result item must match the advanced part (aq) of the query expression, meaning it will only appear if it matches the selected filters in the search interface.

matchQuery
boolean
Default: false

When set to true, a featured result item must match the basic part (q) of the query expression, meaning it will only appear if it matches the search request provided by the user.

Array of any (Predicate)

The non-QPL conditions under which the rule may apply. The rule will apply when any of these are satisfied.

statementGroupId
string

The unique identifier of the statement group.

Responses

Request samples

Content type
application/json
Example
{
  • "condition": {
    },
  • "defaultMatchOperator": {
    },
  • "description": "Back to school promotion.",
  • "enabled": true,
  • "name": "Back to School",
  • "predicates": [
    ],
  • "statementGroupId": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "includeInFacets": true,
  • "kind": "featured_result",
  • "matchAdvancedQuery": true,
  • "matchQuery": true,
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Bulk delete result rankings rules from a pipeline

Delete multiple result rankings rules in batch for a specific pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The rules to delete

ids
required
Array of strings <= 100 items [ items <= 38 characters ]

A list of resource identifiers to delete. A maximum of 100 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{ }

Get a list of result ranking rules

Get a list of result ranking rules

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
enabledStatus
boolean

The enabled status of result ranking rules to allow in the returned list.

Set to true to only allow rules whose enabled property is set to true, and vice versa.

By default, both enabled and disabled rules are allowed.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

kind
string

The kind of result ranking rules to allow in the returned list (i.e., featured_result or ranking_expression).

By default, both kinds of rules are allowed.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

statementGroupId
string

The unique identifier of the statement group.

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "groupedBy": {
    },
  • "resultRankings": [
    ],
  • "totalCount": 0,
  • "totalPages": 0
}

Copy result rankings rules to a pipeline.

Copies specific result ranking rules from an origin to a target query pipeline. Using the same pipeline as origin and target will duplicate the specified statements in that pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The copy operation to perform.

destinationPipelineId
required
string

The unique identifier of the query pipeline to copy the statements to.

resultRankingIds
required
Array of strings [ 1 .. 15 ] items

The unique identifiers of the result ranking rules to copy.

Responses

Request samples

Content type
application/json
{
  • "destinationPipelineId": "120deecf-7822-4d7b-885f-53f184a3a76",
  • "resultRankingIds": [
    ]
}

Response samples

Content type
application/json
{
  • "resultRankings": [
    ]
}

Duplicate a result ranking rule

Duplicate a result ranking rule

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

resultRankingId
required
string
Example: 120deecf-7822-4d7b-885f-53f184a3a76c

The unique identifier of the result ranking.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "associatedGroup": {
    },
  • "id": "string",
  • "resultRanking": {
    }
}

Validate a single result ranking operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains an operation to validate.

required
any (ResultRankingValidationRequest)
required
any (ResultRankingRuleCreateRequest)
operationType
required
string

Validate the creation of a ResultRanking rule.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate a batch of result ranking operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of any (ResultRankingValidationRequest)

A list of operations to validate.

Array
required
any (ResultRankingRuleCreateRequest)
operationType
required
string

Validate the creation of a ResultRanking rule.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete a result ranking rule

Deletes a result ranking rule

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

resultRankingId
required
string
Example: 120deecf-7822-4d7b-885f-53f184a3a76c

The unique identifier of the result ranking.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Get a result ranking rule

Get a result ranking rule

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

resultRankingId
required
string

The unique identifier of the result ranking.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
Example
{
  • "condition": {
    },
  • "defaultMatchOperator": {
    },
  • "description": "Back to school promotion.",
  • "enabled": true,
  • "isMigrated": true,
  • "name": "Back to School",
  • "predicates": [
    ],
  • "associatedGroup": {
    },
  • "id": "string",
  • "includeInFacets": true,
  • "kind": "featured_result",
  • "matchAdvancedQuery": true,
  • "matchQuery": true,
  • "targets": [
    ]
}

Update a result ranking rule

Update a result ranking rule

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

resultRankingId
required
string
Example: 120deecf-7822-4d7b-885f-53f184a3a76c

The unique identifier of the result ranking.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The result ranking rule to update

kind
required
string

The kind of result ranking.

name
required
string

The name of the result ranking.

required
Array of ResultRankingRuleTargetUniqueId (object) or ResultRankingRuleTargetLocalizedContent (object) or ResultRankingRuleTargetQueryExpression (object) (ResultRankingRuleTargetFeaturedResults)

Documents that will show up when conditions and predicates are met.

object (ResultRankingRuleCondition)
object (PredicateMatchOperator)
description
string

The intended purpose of this result ranking.

enabled
boolean
Default: true

Whether this result ranking should be used by the query pipeline.

includeInFacets
boolean
Default: true
matchAdvancedQuery
boolean
Default: true

When set to true, a featured result item must match the advanced part (aq) of the query expression, meaning it will only appear if it matches the selected filters in the search interface.

matchQuery
boolean
Default: false

When set to true, a featured result item must match the basic part (q) of the query expression, meaning it will only appear if it matches the search request provided by the user.

Array of any (Predicate)

The non-QPL conditions under which the rule may apply. The rule will apply when any of these are satisfied.

statementGroupId
string

The unique identifier of the statement group.

Responses

Request samples

Content type
application/json
Example
{
  • "condition": {
    },
  • "defaultMatchOperator": {
    },
  • "description": "Back to school promotion.",
  • "enabled": true,
  • "name": "Back to School",
  • "predicates": [
    ],
  • "statementGroupId": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "includeInFacets": true,
  • "kind": "featured_result",
  • "matchAdvancedQuery": true,
  • "matchQuery": true,
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Machine learning associations

Returns the version of ML models supported by the organization in the request.

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
"string"

List query pipeline ML model associations

Gets a page of Coveo Machine Learning model associations for a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "totalEntries": 0,
  • "totalPages": 0
}

Associate an existing machine learning model with an existing pipeline.

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
optional

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
modelId
required
string

The unique identifier of the ML model to create an association with.

cacheMaximumAge
string

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.

condition
string

The unique identifier of the condition that must be satisfied for a request to be processed by the ML model.

contentIdKeys
Array of strings

The names of the fields to use to uniquely identify items in the index.

Default: ["permanentid","urihash"]

object

The additional parameters to send to Coveo ML.

Among other things, this can be used to specify the strategy to use when querying a Product Recommendations model (e.g., { "strategy": "frequentBought" }. The valid strategy values are:

  • cart
  • frequentBought
  • frequentViewed
  • popularBought
  • popularViewed
  • recentlyBought
  • recentlyViewed
  • user
description
string

The ML model association description.

object (DynamicNavigationExperienceConfiguration)
enableWordCompletion
boolean

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)
exclusive
boolean

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)
intelligentTermDetection
boolean

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.

Used by the following ML models:

  • Automatic relevance tuning (default value: false)
intelligentTermDetectionPartialMatchKeywords
integer <int32>
Default: 1

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)
intelligentTermDetectionPartialMatchThreshold
string
Default: "60%"

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%)
matchAdvancedExpression
boolean

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)
matchBasicExpression
boolean

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)
maxRecommendations
integer <int32>

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)

object (PassageRetrievalConfiguration)
rankingModifier
integer <int32>

The ranking score modifier the ML model should apply to each item it recommends.

Used by the following ML models:

  • Automatic relevance tuning (default value: 1000)
  • Event recommendation (default value: 1000)"
statementGroupId
string

The unique identifier of the statement group.

useAdvancedConfiguration
boolean

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

Responses

Request samples

Content type
application/json
{
  • "cacheMaximumAge": "PT300S",
  • "condition": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e",
  • "contentIdKeys": [
    ],
  • "customQueryParameters": { },
  • "description": "string",
  • "dynamicNavigationExperience": {
    },
  • "enableWordCompletion": true,
  • "exclusive": true,
  • "intelligentTermDetection": true,
  • "intelligentTermDetectionPartialMatchKeywords": 4,
  • "intelligentTermDetectionPartialMatchThreshold": "75%",
  • "matchAdvancedExpression": true,
  • "matchBasicExpression": true,
  • "maxRecommendations": 0,
  • "modelId": "mycoveocloudorganization_topclicks_My_ART_Model",
  • "passageRetrieval": {
    },
  • "rankingModifier": 500,
  • "statementGroupId": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "useAdvancedConfiguration": true
}

Response samples

Content type
application/json
"string"

List query pipeline ML model associations

Gets a page of Coveo Machine Learning model associations for a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "totalEntries": 0,
  • "totalPages": 0
}

Validate a single Ml model association operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains an operation to validate.

required
object (AssociationValidationRequest)
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
CreateAssociationRequest (object) or EditAssociationRequest (object)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate a batch of Ml model association operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (AssociationValidationRequest)

A list of operations to validate.

Array
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
CreateAssociationRequest (object) or EditAssociationRequest (object)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Remove query pipeline ML model association

Removes a single existing association between a machine learning model and a query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
associationId
required
string
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
"string"

Get a ML model association

Gets a Coveo Machine Learning model association.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
associationId
required
string
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "associatedGroup": null,
  • "condition": "string",
  • "conditionDefinition": "string",
  • "contentIdKeys": [
    ],
  • "customQueryParameters": { },
  • "description": "string",
  • "dynamicNavigationExperience": { },
  • "enableWordCompletion": true,
  • "exclusive": true,
  • "id": "string",
  • "intelligentTermDetection": true,
  • "intelligentTermDetectionPartialMatchKeywords": 0,
  • "intelligentTermDetectionPartialMatchThreshold": "string",
  • "matchAdvancedExpression": true,
  • "matchBasicExpression": true,
  • "maxRecommendations": 0,
  • "modelDisplayName": "string",
  • "modelEngine": "string",
  • "modelId": "string",
  • "modelStatus": "string",
  • "passageRetrieval": {
    },
  • "position": 0,
  • "rankingModifier": 0,
  • "useAdvancedConfiguration": true
}

Update ML model association

Changes the configuration of an association in a pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
associationId
required
string
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
optional

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
cacheMaximumAge
string

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.

condition
string

The unique identifier of the condition that must be satisfied for a request to be processed by the ML model.

contentIdKeys
Array of strings

The names of the fields to use to uniquely identify items in the index.

Default: ["permanentid","urihash"]

object

The additional parameters to send to Coveo ML.

Among other things, this can be used to specify the strategy to use when querying a Product Recommendations model (e.g., { "strategy": "frequentBought" }. The valid strategy values are:

  • cart
  • frequentBought
  • frequentViewed
  • popularBought
  • popularViewed
  • recentlyBought
  • recentlyViewed
  • user
description
string

The ML model association description.

object (DynamicNavigationExperienceConfiguration)
enableWordCompletion
boolean

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)
exclusive
boolean

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)
intelligentTermDetection
boolean

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.

Used by the following ML models:

  • Automatic relevance tuning (default value: false)
intelligentTermDetectionPartialMatchKeywords
integer <int32>
Default: 1

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)
intelligentTermDetectionPartialMatchThreshold
string
Default: "60%"

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%)
matchAdvancedExpression
boolean

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)
matchBasicExpression
boolean

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)
maxRecommendations
integer <int32>

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)

object (PassageRetrievalConfiguration)
rankingModifier
integer <int32>

The ranking score modifier the ML model should apply to each item it recommends.

Used by the following ML models:

  • Automatic relevance tuning (default value: 1000)
  • Event recommendation (default value: 1000)
statementGroupId
string

The unique identifier of the statement group.

useAdvancedConfiguration
boolean

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

Responses

Request samples

Content type
application/json
{
  • "cacheMaximumAge": "PT300S",
  • "condition": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e",
  • "contentIdKeys": [
    ],
  • "customQueryParameters": { },
  • "description": "string",
  • "dynamicNavigationExperience": {
    },
  • "enableWordCompletion": true,
  • "exclusive": true,
  • "intelligentTermDetection": true,
  • "intelligentTermDetectionPartialMatchKeywords": 4,
  • "intelligentTermDetectionPartialMatchThreshold": "75%",
  • "matchAdvancedExpression": true,
  • "matchBasicExpression": true,
  • "maxRecommendations": 0,
  • "passageRetrieval": {
    },
  • "rankingModifier": 500,
  • "statementGroupId": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "useAdvancedConfiguration": true
}

Response samples

Content type
application/json
"string"

Update ML model association position

Changes the position of an association in a pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
associationId
required
string
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

position
required
integer <int32>

Responses

Response samples

Content type
application/json
"string"

Statement groups

Returns the list of all pipeline features and whether they're active or not.

undefined

Privilege(s) required

Authorizations:
oauth2
query Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
{
  • "featureActiveState": [
    ]
}

List statement groups of a pipeline

List statement groups of a pipeline

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string
Default: "status"
Enum: "name" "status"

The sort criteria to apply on the results.

name : Sort results in alphabetical order

status: Sort results according to their activation status (i.e., Active, Inactive, Not Yet Started, Expire)

status
Array of strings (StatementGroupStatus) non-empty
Items Enum: "active" "inactive" "expired" "notStarted"

The status of the statement group.

types
Array of strings (StatementGroupType) non-empty
Items Enum: "campaign" "permanent"

The type name of the statement group.

Responses

Response samples

Content type
application/json
{
  • "groupComposition": {
    },
  • "groups": [
    ],
  • "totalCount": 1
}

Create a new statement group

Create a new statement group

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The new statement group to create

campaignEnd
required
string

The end date of the campaign.

campaignStart
required
string

The start date of the campaign.

name
required
string

The name of the statement group.

type
required
string (StatementGroupType)

The type name of the statement group.

conditionId
string

The condition that must be met by a query in order to route that query through this query pipeline.

Typically, each query pipeline except the default one should have a condition, and you should ensure that the conditions you set on query pipelines are mutually exclusive.

Note:

A query cannot be routed through a query pipeline that does not have a condition unless:

  • That query pipeline is set as the default query pipeline (see the isDefault property), or
  • That query pipeline is enforced through the pipeline parameter of the query itself, in which case the query pipeline condition is bypassed.
description
string

The intended purpose of this statement group.

Responses

Request samples

Content type
application/json
Example
{
  • "conditionId": "string",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "name": "Community",
  • "type": "campaign",
  • "campaignEnd": "2002-09-07T10:07:20-04:00",
  • "campaignStart": "2001-07-20T23:01:05-04:00"
}

Response samples

Content type
application/json
{
  • "campaignEnd": "2002-09-07T10:07:20",
  • "campaignStart": "2001-07-20T23:01:05",
  • "conditionId": "string",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "id": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "isActive": false,
  • "name": "Community",
  • "type": "campaign"
}

Dissociate pipeline rules associated to groups

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
Array of objects (StatementGroupAssociationItem) <= 50 items

The rules that should be dissociated from their group, if any.

If a rule is not associated to a group, it won't be updated.

Note:: Invalid rule IDs will cause the request to fail.

Array (<= 50 items)
featureType
required
string
Value: "resultRankings"

The query pipeline feature that's enabled by this rule.

ruleId
required
string

The unique identifier of the rule.

Responses

Request samples

Content type
application/json
{
  • "associations": [
    ]
}

Response samples

Content type
application/json
{ }

List statement groups of a pipeline

List statement groups of a pipeline

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "groupComposition": {
    },
  • "groups": [
    ],
  • "totalCount": 1
}

Validate a single statement group operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains an operation to validate.

required
object (RestOperationValidationRequestCreateStatementGroupRequest)
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
any (CreateOrUpdateStatementGroup)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate a batch of statement groups operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (RestOperationValidationRequestCreateStatementGroupRequest)

A list of operations to validate.

Array
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
any (CreateOrUpdateStatementGroup)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete a statement group of a pipeline

Delete a statement group of a pipeline

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementGroupId
required
string
Example: 679adb80-444e-11ea-b77f-2e728ce88125

The unique identifier of the statement group.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Get a statement group of a pipeline

Get a statement group of a pipeline

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementGroupId
required
string
Example: 679adb80-444e-11ea-b77f-2e728ce88125

The unique identifier of the statement group.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
Example
{
  • "conditionDefinition": "string",
  • "conditionDetailed": null,
  • "conditionId": "string",
  • "createdAt": "string",
  • "createdBy": "string",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "id": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "modifiedAt": "string",
  • "modifiedBy": "string",
  • "name": "Community",
  • "statementComposition": {
    },
  • "type": "campaign",
  • "warnings": [
    ],
  • "campaignEnd": "2002-09-07T10:07:20-04:00",
  • "campaignStart": "2001-07-20T23:01:05-04:00",
  • "status": "active"
}

Toggle a permanent group

Toggle a permanent group

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementGroupId
required
string
Example: 679adb80-444e-11ea-b77f-2e728ce88125

The unique identifier of the statement group.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required
isActive
boolean

Whether or not the group is active.

Responses

Request samples

Content type
application/json
{
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Update a statement group

Update a statement group

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementGroupId
required
string
Example: 679adb80-444e-11ea-b77f-2e728ce88125

The unique identifier of the statement group.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The statement group to update

campaignEnd
required
string

The end date of the campaign.

campaignStart
required
string

The start date of the campaign.

name
required
string

The name of the statement group.

type
required
string (StatementGroupType)

The type name of the statement group.

conditionId
string

The condition that must be met by a query in order to route that query through this query pipeline.

Typically, each query pipeline except the default one should have a condition, and you should ensure that the conditions you set on query pipelines are mutually exclusive.

Note:

A query cannot be routed through a query pipeline that does not have a condition unless:

  • That query pipeline is set as the default query pipeline (see the isDefault property), or
  • That query pipeline is enforced through the pipeline parameter of the query itself, in which case the query pipeline condition is bypassed.
description
string

The intended purpose of this statement group.

Responses

Request samples

Content type
application/json
Example
{
  • "conditionId": "string",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "name": "Community",
  • "type": "campaign",
  • "campaignEnd": "2002-09-07T10:07:20-04:00",
  • "campaignStart": "2001-07-20T23:01:05-04:00"
}

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Update the rules associated with a statement group

There are two operations which can update the rules associated with a statement group:

  • Addition uses the toAdd parameter
  • Deletion uses the toRemove parameter
    Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementGroupId
required
string
Example: 679adb80-444e-11ea-b77f-2e728ce88125

The unique identifier of the statement group.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
Array of objects (StatementGroupAssociationItem) <= 50 items

The rules to add to this group.

If you specify a rule from another group, it will be removed from the original group and added to this one instead.

Note: Invalid rule IDs will cause the request to fail.

Array of objects (StatementGroupAssociationItem) <= 50 items

The rules to remove from this group.

Note: Orphaned rules, rules that are associated with another group, and non-existent rules will be ignored.

Responses

Request samples

Content type
application/json
{
  • "toAdd": [
    ],
  • "toRemove": [
    ]
}

Response samples

Content type
application/json
{
  • "associatedRules": [
    ]
}

Featured results

DEPRECATED - Get a list of featured result rules Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Responses

Response samples

Content type
application/json
{
  • "featuredResultRules": [
    ],
  • "totalCount": 0,
  • "totalPages": 0
}

DEPRECATED - Create a new featured result rule Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The new featured result rule to create

required
object (FeaturedResultRuleMatchOperator)
name
required
string
required
Array of objects (FeaturedResultRulePredicate)

Search queries that will trigger this featured result to be shown.

required
Array of objects (FeaturedResultRuleTarget)

Documents that will be shown as featured results.

object (FeaturedResultRuleCondition)
description
string
enabled
boolean

Whether this featured result should be used by the query pipeline.

includeInFacets
boolean
matchAdvancedQuery
boolean
matchQuery
boolean
Array of objects (FeaturedResultQPLCodePredicate)
rankingModifier
integer <int32>

The ranking score modifier to apply.

Use a positive value to promote the target, or a negative value to demote it.

Note: If you do not specify a value for this parameter, the target will receive a significant boost, causing it to appear at the top of the ranked query result set.

statementGroupId
string

The unique identifier of the statement group.

Responses

Request samples

Content type
application/json
{
  • "condition": {
    },
  • "defaultMatchOperator": {
    },
  • "description": "string",
  • "enabled": true,
  • "includeInFacets": true,
  • "matchAdvancedQuery": true,
  • "matchQuery": true,
  • "name": "winterPromotion01",
  • "predicates": [
    ],
  • "qplPredicates": [
    ],
  • "rankingModifier": 1000,
  • "statementGroupId": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string"
}

DEPRECATED - Get a list of featured result rules Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "featuredResultRules": [
    ],
  • "totalCount": 0,
  • "totalPages": 0
}

DEPRECATED - Validate a single featured result operation. Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains an operation to validate.

required
object (FeaturedResultRuleValidationRequest)
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (CreateFeaturedResultRuleRequest)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

DEPRECATED - Validate a batch of featured results operations. Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (FeaturedResultRuleValidationRequest)

A list of operations to validate.

Array
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (CreateFeaturedResultRuleRequest)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

DEPRECATED - Delete a featured result rule Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
featuredResultId
required
string

The unique identifier of the featured result.

pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
"string"

DEPRECATED - Get a featured result rule Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
featuredResultId
required
string

The unique identifier of the featured result.

pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "condition": {
    },
  • "defaultMatchOperator": {
    },
  • "description": "string",
  • "enabled": true,
  • "includeInFacets": true,
  • "isMigrated": true,
  • "matchAdvancedQuery": true,
  • "matchQuery": true,
  • "name": "winterPromotion01",
  • "predicates": [
    ],
  • "qplPredicates": [
    ],
  • "rankingModifier": 1000,
  • "targets": [
    ]
}

DEPRECATED - Update a featured result rule Deprecated

This API is deprecated and will be removed on 2025-02-17. We recommend that you switch to the /resultRankings endpoint before this date to maintain functionality.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
featuredResultId
required
string

The unique identifier of the featured result.

pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The featured result rule to update

required
object (FeaturedResultRuleMatchOperator)
name
required
string
required
Array of objects (FeaturedResultRulePredicate)

Search queries that will trigger this featured result to be shown.

required
Array of objects (FeaturedResultRuleTarget)

Documents that will be shown as featured results.

object (FeaturedResultRuleCondition)
description
string
enabled
boolean

Whether this featured result should be used by the query pipeline.

includeInFacets
boolean
matchAdvancedQuery
boolean
matchQuery
boolean
Array of objects (FeaturedResultQPLCodePredicate)
rankingModifier
integer <int32>

The ranking score modifier to apply.

Use a positive value to promote the target, or a negative value to demote it.

Note: If you do not specify a value for this parameter, the target will receive a significant boost, causing it to appear at the top of the ranked query result set.

statementGroupId
string

The unique identifier of the statement group.

Responses

Request samples

Content type
application/json
{
  • "condition": {
    },
  • "defaultMatchOperator": {
    },
  • "description": "string",
  • "enabled": true,
  • "includeInFacets": true,
  • "matchAdvancedQuery": true,
  • "matchQuery": true,
  • "name": "winterPromotion01",
  • "predicates": [
    ],
  • "qplPredicates": [
    ],
  • "rankingModifier": 1000,
  • "statementGroupId": "679adb80-444e-11ea-b77f-2e728ce88125",
  • "targets": [
    ]
}

Pipelines

List query pipelines

Gets a sorted page of query pipelines matching certain criteria.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
enablePagination
boolean

Whether to receive the pipelines in a paginated format.

excludeAbTestTargets
boolean
Default: false

Whether to exclude the A/B test targets from the result.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalEntries": 0
}

Create query pipeline

Creates a new query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"CREATE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The query pipeline information.

name
required
string

The name of this query pipeline.

object (PipelineAduiConfiguration)
Array of objects (IdentifiedResource)
object (IncomingConditionReference)
description
string

The intended purpose of this query pipeline.

filter
string
Array of objects (IdentifiedResource)
Array of objects (PipelineInterfaceUrls) <= 20 items

This option helps better understand the pages where this query pipeline is intended to be used. It won't affect query routing in any way but may be used by Coveo to help you manage your configuration properly.

isDefault
boolean

Whether this query pipeline is the default query pipeline.

Note: There must be one and only one default query pipeline in a Coveo Cloud organization. Therefore, setting isDefault to true on this query pipeline will automatically set it to false in the current default query pipeline as a side effect (assuming, of course, that this query pipeline is not the current default query pipeline).

splitTestEnabled
boolean

Whether to enable the A/B test.

See also the splitTestName, splitTestTarget, and splitTestRatio properties.

splitTestName
string

A name which summarizes the intended purpose of the A/B test.

See also the splitTestTarget, splitTestRatio, and splitTestEnabled properties.

splitTestRatio
number <double> [ 0 .. 1 ]

The percentage of queries to route through query pipeline B if the A/B test is enabled. Remaining queries will be routed through this query pipeline.

See also the splitTestName, splitTestTarget, and splitTestEnabled properties.

splitTestTarget
string

The unique identifier of query pipeline B in the A/B test.

See also the splitTestName, splitTestRatio, and splitTestEnabled properties.

useCase
string <= 50 characters

The use case for which this query pipeline should apply. This option allows you to categorize your query pipeline and enables Coveo to provide better support and improve the tools we provide.

Responses

Request samples

Content type
application/json
{
  • "aduiConfig": {
    },
  • "apiKeysThatCanEdit": [
    ],
  • "condition": {
    },
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "filter": "string",
  • "groupsThatCanEdit": [
    ],
  • "interfaceUrls": [
    ],
  • "isDefault": false,
  • "name": "Community",
  • "splitTestEnabled": true,
  • "splitTestName": "Community VS default",
  • "splitTestRatio": 0.5,
  • "splitTestTarget": "22a3860e-fa6f-4e64-a9f1-ef738af0786e",
  • "useCase": "Service & Support"
}

Response samples

Content type
application/json
{
  • "aduiConfig": {
    },
  • "condition": {
    },
  • "created_by": "asmith@example.com",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "filter": "@source==CommunityForum OR @source==CommunityDocumentation",
  • "id": "120deecf-7822-4d7b-885f-53f184a3a76c",
  • "interfaceUrls": [
    ],
  • "isDefault": false,
  • "last_modified_by": "bjones@example.com",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "name": "Community",
  • "position": 3,
  • "splitTestEnabled": true,
  • "splitTestName": "Community VS default",
  • "splitTestRatio": 0.5,
  • "splitTestTarget": "22a3860e-fa6f-4e64-a9f1-ef738af0786e",
  • "useCase": "Service & Support"
}

List query pipelines

Gets a sorted page of query pipelines matching certain criteria.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "pipelines": [
    ],
  • "totalEntries": 0
}

Validate a single pipeline operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that describes the operation to validate, the resource to target, and the model payload to use.

required
object (RestOperationValidationRequestIncomingPipeline)
operationType
required
string (ValidationOperationType)
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingPipeline)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate batch of pipeline operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (RestOperationValidationRequestIncomingPipeline)

A list of operations to validate.

Array
operationType
required
string (ValidationOperationType)
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingPipeline)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete query pipeline

Deletes a single query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
"string"

Get query pipeline

Gets a single query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "aduiConfig": {
    },
  • "condition": {
    },
  • "created_by": "asmith@example.com",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "filter": "@source==CommunityForum OR @source==CommunityDocumentation",
  • "id": "120deecf-7822-4d7b-885f-53f184a3a76c",
  • "interfaceUrls": [
    ],
  • "isDefault": false,
  • "last_modified_by": "bjones@example.com",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "name": "Community",
  • "position": 3,
  • "splitTestEnabled": true,
  • "splitTestName": "Community VS default",
  • "splitTestRatio": 0.5,
  • "splitTestTarget": "22a3860e-fa6f-4e64-a9f1-ef738af0786e",
  • "useCase": "Service & Support",
  • "splitTestOriginalPipeline": "string",
  • "statementComposition": {
    }
}

Update query pipeline

Modifies a single query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The updated query pipeline information.

name
required
string

The name of this query pipeline.

object (PipelineAduiConfiguration)
Array of objects (IdentifiedResource)
object (IncomingConditionReference)
description
string

The intended purpose of this query pipeline.

filter
string
Array of objects (IdentifiedResource)
Array of objects (PipelineInterfaceUrls) <= 20 items

This option helps better understand the pages where this query pipeline is intended to be used. It won't affect query routing in any way but may be used by Coveo to help you manage your configuration properly.

isDefault
boolean

Whether this query pipeline is the default query pipeline.

Note: There must be one and only one default query pipeline in a Coveo Cloud organization. Therefore, setting isDefault to true on this query pipeline will automatically set it to false in the current default query pipeline as a side effect (assuming, of course, that this query pipeline is not the current default query pipeline).

splitTestEnabled
boolean

Whether to enable the A/B test.

See also the splitTestName, splitTestTarget, and splitTestRatio properties.

splitTestName
string

A name which summarizes the intended purpose of the A/B test.

See also the splitTestTarget, splitTestRatio, and splitTestEnabled properties.

splitTestRatio
number <double> [ 0 .. 1 ]

The percentage of queries to route through query pipeline B if the A/B test is enabled. Remaining queries will be routed through this query pipeline.

See also the splitTestName, splitTestTarget, and splitTestEnabled properties.

splitTestTarget
string

The unique identifier of query pipeline B in the A/B test.

See also the splitTestName, splitTestRatio, and splitTestEnabled properties.

useCase
string <= 50 characters

The use case for which this query pipeline should apply. This option allows you to categorize your query pipeline and enables Coveo to provide better support and improve the tools we provide.

Responses

Request samples

Content type
application/json
{
  • "aduiConfig": {
    },
  • "apiKeysThatCanEdit": [
    ],
  • "condition": {
    },
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "filter": "string",
  • "groupsThatCanEdit": [
    ],
  • "interfaceUrls": [
    ],
  • "isDefault": false,
  • "name": "Community",
  • "splitTestEnabled": true,
  • "splitTestName": "Community VS default",
  • "splitTestRatio": 0.5,
  • "splitTestTarget": "22a3860e-fa6f-4e64-a9f1-ef738af0786e",
  • "useCase": "Service & Support"
}

Response samples

Content type
application/json
{
  • "aduiConfig": {
    },
  • "condition": {
    },
  • "created_by": "asmith@example.com",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "filter": "@source==CommunityForum OR @source==CommunityDocumentation",
  • "id": "120deecf-7822-4d7b-885f-53f184a3a76c",
  • "interfaceUrls": [
    ],
  • "isDefault": false,
  • "last_modified_by": "bjones@example.com",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "name": "Community",
  • "position": 3,
  • "splitTestEnabled": true,
  • "splitTestName": "Community VS default",
  • "splitTestRatio": 0.5,
  • "splitTestTarget": "22a3860e-fa6f-4e64-a9f1-ef738af0786e",
  • "useCase": "Service & Support"
}

Copy query pipeline

Duplicates a single query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"CREATE","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json

The permissions to set on the duplicated pipeline

Array of objects (IdentifiedResource)
Array of objects (IdentifiedResource)

Responses

Request samples

Content type
application/json
{
  • "apiKeysThatCanEdit": [
    ],
  • "groupsThatCanEdit": [
    ]
}

Response samples

Content type
application/json
{
  • "aduiConfig": {
    },
  • "condition": {
    },
  • "created_by": "asmith@example.com",
  • "description": "Provide contextually relevant query recommendations/results to Community site users.",
  • "filter": "@source==CommunityForum OR @source==CommunityDocumentation",
  • "id": "120deecf-7822-4d7b-885f-53f184a3a76c",
  • "interfaceUrls": [
    ],
  • "isDefault": false,
  • "last_modified_by": "bjones@example.com",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "name": "Community",
  • "position": 3,
  • "splitTestEnabled": true,
  • "splitTestName": "Community VS default",
  • "splitTestRatio": 0.5,
  • "splitTestTarget": "22a3860e-fa6f-4e64-a9f1-ef738af0786e",
  • "useCase": "Service & Support"
}

Import query pipeline statements

Import the definition, condition, and description of statements from a CSV file to a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: multipart/form-data
fileName
required
string <binary>

Responses

Response samples

Content type
application/json
"string"

Swap query pipeline names

Swaps the names of two query pipelines. Doing so will affect the routing of incoming queries whose pipeline parameter is defined as the name value of one of the swapped query pipelines.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

other
required
string

The unique identifier of the query pipeline to swap names with.

Responses

Response samples

Content type
application/json
"string"

Statements

List query pipeline statements

Gets a sorted page of query pipeline statements matching certain criteria from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Responses

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Create query pipeline statement

Creates a new query pipeline statement in a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The query pipeline statement information.

definition
required
string

The query pipeline language expression that defines this statement (see Query Pipeline Language (QPL)).

feature
required
string
Enum: "filter" "trigger" "ranking" "stop" "thesaurus" … 6 more

The query pipeline feature expressed by this statement (see Query Pipeline Language (QPL)).

description
string

The intended purpose of this statement in an actual implementation.

id
string

The unique identifier of this statement.

parent
string

The unique identifier of the condition that must be met for this statement to apply.

Responses

Request samples

Content type
application/json
{
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "feature": "ranking",
  • "id": "string",
  • "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": {
    },
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "detailed": null,
  • "displayName": "",
  • "feature": "ranking",
  • "id": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": {
    },
  • "position": 2,
  • "ready": false,
  • "statementGroupId": "string",
  • "warnings": [
    ]
}

List query pipeline statements

Gets a sorted page of query pipeline statements matching certain criteria from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Copy query pipeline statements

Copies specific statements from an origin to a target query pipeline. Using the same pipeline as origin and target will duplicate the specified statements in that pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The copy operation to perform.

destinationPipelineId
required
string

The unique identifier of the query pipeline to copy the statements to.

statementIds
required
Array of strings

The unique identifiers of the query pipeline statements to copy.

Responses

Request samples

Content type
application/json
{
  • "destinationPipelineId": "120deecf-7822-4d7b-885f-53f184a3a76",
  • "statementIds": [
    ]
}

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Export query pipeline statements

Exports the definition, condition, and description of statements from a specific query pipeline to a CSV file.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
feature
string

The query pipeline feature to match.

Allowed values: when, filter, trigger, ranking, stop, thesaurus, top, topClicks, completion, querySuggest, rankingweight, recommendation, and queryParamOverride.

By default, results are not required to match a specific query pipeline feature.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "message": "Bad request.",
  • "statusCode": 400
}

Validate a single statement operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains an operation to validate.

required
object (RestOperationValidationRequestIncomingStatement)
operationType
required
string (ValidationOperationType)
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingStatement)
resourceId
string

The identifier of the resource when operationType is UPDATE or DELETE.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate a batch of statement operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (RestOperationValidationRequestIncomingStatement)

A list of operations to validate.

Array
operationType
required
string (ValidationOperationType)
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingStatement)
resourceId
string

The identifier of the resource when operationType is UPDATE or DELETE.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete query pipeline statement

Deletes a single query pipeline statement from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
"string"

Get query pipeline statement

Gets a single query pipeline statement from a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": {
    },
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "detailed": null,
  • "displayName": "",
  • "feature": "ranking",
  • "id": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": {
    },
  • "position": 2,
  • "ready": false,
  • "statementGroupId": "string",
  • "warnings": [
    ]
}

Update query pipeline statement

Updates a single query pipeline statement in a specific query pipeline.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"{pipelineId}"},
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The updated query pipeline statement information.

definition
required
string

The query pipeline language expression that defines this statement (see Query Pipeline Language (QPL)).

feature
required
string
Enum: "filter" "trigger" "ranking" "stop" "thesaurus" … 6 more

The query pipeline feature expressed by this statement (see Query Pipeline Language (QPL)).

description
string

The intended purpose of this statement in an actual implementation.

id
string

The unique identifier of this statement.

parent
string

The unique identifier of the condition that must be met for this statement to apply.

Responses

Request samples

Content type
application/json
{
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "feature": "ranking",
  • "id": "string",
  • "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": {
    },
  • "definition": "boost `coveo` by 100",
  • "description": "Spotlight the Coveo brand in query results.",
  • "detailed": null,
  • "displayName": "",
  • "feature": "ranking",
  • "id": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": {
    },
  • "position": 2,
  • "ready": false,
  • "statementGroupId": "string",
  • "warnings": [
    ]
}

Move query pipeline statement

Sets the position of a query pipeline statement in a specific query pipeline and updates other statement positions as appropriate.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"{pipelineId}"}
Authorizations:
oauth2
path Parameters
pipelineId
required
string

The unique identifier of the target query pipeline.

statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The move operation to perform.

after
string

The unique identifier of the statement after which to move this statement in the target query pipeline.

Use either this property or the position property (not both) to move this statement.

pageSize
integer <int32>
Deprecated

This parameter is exposed for backward compatibility reasons only.

position
integer <int32>

The 1-based position of this statement relative to other statements in the target query pipeline.

Use either this property or the after property (not both) to move this statement.

Responses

Request samples

Content type
application/json
{
  • "after": "0befc717-dfd7-4962-9b85-28f5c26fd23b",
  • "pageSize": 0,
  • "position": 0
}

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Conditions

List condition statements

Gets a sorted page of condition statements matching certain criteria.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Responses

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Create condition statement

Creates a new condition statement.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The condition statement information.

definition
required
string <= 10000 characters

The query pipeline language expression that defines this statement (see Query Pipeline Language (QPL)).

description
string

The intended purpose of this statement in an actual implementation.

Responses

Request samples

Content type
application/json
{
  • "definition": "when $searchhub is \"community\"",
  • "description": "If the query originates from the community site..."
}

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": "string",
  • "definition": "when $searchhub is \"community\"",
  • "description": "If the query originates from the community site...",
  • "detailed": {
    },
  • "feature": "when",
  • "id": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": "string",
  • "position": 0,
  • "ready": true
}

List condition statements

Gets a sorted page of condition statements matching certain criteria.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
filter
string

The query filter to match.

This allows you to search within query pipeline statement definitions and descriptions.

By default, results are not required to match a specific query filter.

isOrderAscending
boolean
Default: true

Whether to sort the results in ascending order.

organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

sortBy
string

The sort criteria to apply on the results.

Allowed values: definition, description, and position.

Default: position

Request Body schema: application/json
required

A set of parameters to customize the results.

ids
Array of strings[ items <= 1000 items ]

A list of resource identifiers to get. A maximum of 1000 can be sent.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "statements": [
    ],
  • "totalCount": 1,
  • "totalEntries": 1,
  • "totalPages": 1
}

Validate a single pipeline condition operation.

Validate that a specific operation would be accepted by our API and executed.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that describes the operation to validate, the resource to target, and the model payload to use.

required
object (RestOperationValidationRequestIncomingCondition)
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingCondition)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operation": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Validate batch of pipeline condition operations.

Validate that a list of operations would be accepted by our API and executed. A maximum of 15 can be processed per request.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

An object that contains the list of operations to validate.

required
Array of objects (RestOperationValidationRequestIncomingCondition)

A list of operations to validate.

Array
operationType
required
string
Enum: "CREATE" "UPDATE" "DELETE"

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.
object (IncomingCondition)
resourceId
string

The identifier of the resource.

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete condition statement

Deletes a single condition statement.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"*"}
Authorizations:
oauth2
path Parameters
statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Get condition statement

Gets a single condition statement.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"VIEW","targetId":"*"}
Authorizations:
oauth2
path Parameters
statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Responses

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": "string",
  • "definition": "when $searchhub is \"community\"",
  • "description": "If the query originates from the community site...",
  • "detailed": {
    },
  • "feature": "when",
  • "id": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": "string",
  • "position": 0,
  • "ready": true
}

Update condition statement

Updates a single condition statement.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"QUERY_PIPELINE","type":"EDIT","targetId":"*"}
Authorizations:
oauth2
path Parameters
statementId
required
string

The unique identifier of the target statement.

query Parameters
organizationId
string
Example: organizationId=mycoveocloudv2organization

The unique identifier of the target Coveo Cloud organization.

Specifying a value for this parameter is only necessary when you are authenticating the API call with an OAuth2 token.

Request Body schema: application/json
required

The updated condition statement information

definition
required
string <= 10000 characters

The query pipeline language expression that defines this statement (see Query Pipeline Language (QPL)).

description
string

The intended purpose of this statement in an actual implementation.

Responses

Request samples

Content type
application/json
{
  • "definition": "when $searchhub is \"community\"",
  • "description": "If the query originates from the community site..."
}

Response samples

Content type
application/json
{
  • "childrenCount": 0,
  • "condition": "string",
  • "definition": "when $searchhub is \"community\"",
  • "description": "If the query originates from the community site...",
  • "detailed": {
    },
  • "feature": "when",
  • "id": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e",
  • "modifiedAt": "2021-02-16T15:15:17Z",
  • "modifiedBy": "bjones@example.com",
  • "parent": "string",
  • "position": 0,
  • "ready": true
}

Passages Alpha

Allow to debug passage(s) retrieval.

API that allows to debug how the passage(s) retrieval was performed for a particular query.

Note: The debug endpoint of the Passage Retrieval API is currently in alpha.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
query Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

viewAllContent
boolean

Whether to bypass document permissions. Only effective if the access token grants the Search - View all content privilege.

Request Body schema: application/json
required
object

Localization parameter.

query
required
string <= 1000 characters

The query for which to retrieve the passage(s).

additionalFields
Array of strings <= 5 items [^([a-z][a-z0-9_]{0,254})$]

The fields to include in the response.

When omitted, only the identifier of the document will be returned.

object or null

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

filter
string

A filter expression that will be applied during the first stage retrieval.

The expression must comply with the Coveo Query Language (CQL) syntax.

maxPassages
integer <int32> [ 1 .. 20 ]
Default: 5

The maximum number of passage(s) to retrieve.

searchHub
string

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

Responses

Request samples

Content type
application/json
{
  • "additionalFields": [
    ],
  • "context": {
    },
  • "filter": "@source==\"acme\"\n",
  • "localization": {
    },
  • "maxPassages": 5,
  • "query": "What are the benefits of using solar energy?",
  • "searchHub": "Main"
}

Response samples

Content type
application/json
{
  • "firstStageRetrievalResults": [
    ],
  • "passages": [
    ],
  • "responseId": "c0857557-5579-4f5e-8958-9befd7d1d4a8",
  • "warnings": [
    ]
}

Organizations

Lists all authentication providers for an organization

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lists the SAML authentications for an organization

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new SAML authentication in an organization

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Request Body schema: application/json
required

The SAML authentication data

expiration
required
integer <int32>
metadata
required
string
name
required
string
assertionConsumerServiceUrl
string
enforceTrustedUris
boolean
Default: true
relyingPartyIdentifier
string

Responses

Request samples

Content type
application/json
{
  • "assertionConsumerServiceUrl": "string",
  • "enforceTrustedUris": true,
  • "expiration": 0,
  • "metadata": "string",
  • "name": "string",
  • "relyingPartyIdentifier": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Deletes a SAML authentication from an organization

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string

The SAML authentication ID

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Loads a single SAML authentication from an organization

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string

The SAML authentication ID

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
{
  • "assertionConsumerServiceUrl": "string",
  • "enforceTrustedUris": true,
  • "expiration": 0,
  • "id": "string",
  • "metadata": "string",
  • "name": "string",
  • "organization": "string",
  • "protocol": "SAML",
  • "provider": "string",
  • "relyingPartyIdentifier": "string",
  • "secret": "string"
}

Updates a SAML authentication in an organization

undefined

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string

The SAML authentication ID

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Request Body schema: application/json
required

The SAML authentication data

expiration
required
integer <int32>
metadata
required
string
name
required
string
assertionConsumerServiceUrl
string
enforceTrustedUris
boolean
Default: true
relyingPartyIdentifier
string

Responses

Request samples

Content type
application/json
{
  • "assertionConsumerServiceUrl": "string",
  • "enforceTrustedUris": true,
  • "expiration": 0,
  • "metadata": "string",
  • "name": "string",
  • "relyingPartyIdentifier": "string"
}

List SharePoint claims authentication providers

Gets all SharePoint claims authentication providers in a Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create SharePoint claims authentication provider

Configures a new SharePoint claims authentication provider in a Coveo Cloud organization, allowing you to implement claims authentication in a search page (see Claims Authentication).

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Request Body schema: application/json
required

The SharePoint claims authentication provider information.

expiration
required
integer <int32>

The amount of time (in milliseconds) the browser cookie that stores the claims information should last.

Setting this property to 0 expires the cookie when the browser session ends.

Note:

When cookies aren't supported by your browser, a JWT token will be used instead. For JWT tokens, the expiration must be between 15 minutes and 24 hours. Any value outside of these limits will be capped, with the exception of a 0 value which will be converted to the longest supported value (24 hours).

name
required
string

The name of this SharePoint claims authentication provider.

provider
required
string

The name of the security identity provider which is associated to your SharePoint source in your Coveo Cloud organization.

uri
required
string

The URI of the page that serves the claims information for this SharePoint server.

Note:

This page is part of the Coveo SharePoint integration. You must install this package on your SharePoint server if you want to implement claims authentication in a search page (see Installing the Coveo Web Service, Search Box, and Search Interface into SharePoint).

enforceTrustedUris
boolean
Default: true
secret
string

The string to use when signing claims information. This should be a random string. The longer the string, the safer.

Responses

Request samples

Content type
application/json
{
  • "enforceTrustedUris": true,
  • "expiration": 86400000,
  • "name": "My SharePoint Claims Authentication Provider",
  • "provider": "My SharePoint Server Security Identity Provider",
  • "secret": "k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN",
}

Response samples

Content type
application/json
{
  • "id": "beffaaed-1c4b-44c0-ad9a-ce95b9b169e5"
}

Delete SharePoint claims authentication provider

Removes an existing SharePoint claims authentication provider from a Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string
Example: 120deecf-7822-4d7b-885f-53f184a3a76c

The unique identifier of the target SharePoint claims authentication provider.

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
"string"

Get SharePoint claims authentication provider

Retrieves a single SharePoint claims authentication provider in a Coveo Cloud organization

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string

The unique identifier of the target SharePoint claims authentication provider.

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
{
  • "enforceTrustedUris": true,
  • "expiration": 86400000,
  • "id": "beffaaed-1c4b-44c0-ad9a-ce95b9b169e5",
  • "name": "My SharePoint Claims Authentication Provider",
  • "organization": "mycoveocloudv2organization",
  • "protocol": "SharePoint",
  • "provider": "My SharePoint Server Security Identity Provider",
  • "secret": "k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN",
}

Update SharePoint claims authentication provider

Modifies an existing SharePoint claims authentication provider in a Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string
Example: 120deecf-7822-4d7b-885f-53f184a3a76c

The unique identifier of the target SharePoint claims authentication provider.

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Request Body schema: application/json
required

The updated SharePoint claims authentication provider information.

expiration
required
integer <int32>

The amount of time (in milliseconds) the browser cookie that stores the claims information should last.

Setting this property to 0 expires the cookie when the browser session ends.

Note:

When cookies aren't supported by your browser, a JWT token will be used instead. For JWT tokens, the expiration must be between 15 minutes and 24 hours. Any value outside of these limits will be capped, with the exception of a 0 value which will be converted to the longest supported value (24 hours).

name
required
string

The name of this SharePoint claims authentication provider.

provider
required
string

The name of the security identity provider which is associated to your SharePoint source in your Coveo Cloud organization.

uri
required
string

The URI of the page that serves the claims information for this SharePoint server.

Note:

This page is part of the Coveo SharePoint integration. You must install this package on your SharePoint server if you want to implement claims authentication in a search page (see Installing the Coveo Web Service, Search Box, and Search Interface into SharePoint).

enforceTrustedUris
boolean
Default: true
secret
string

The string to use when signing claims information. This should be a random string. The longer the string, the safer.

Responses

Request samples

Content type
application/json
{
  • "enforceTrustedUris": true,
  • "expiration": 86400000,
  • "name": "My SharePoint Claims Authentication Provider",
  • "provider": "My SharePoint Server Security Identity Provider",
  • "secret": "k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN",
}

Response samples

Content type
application/json
"string"

List trusted search page URIs

Gets all existing trusted search page URI entries in a specific Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

query Parameters
page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Responses

Response samples

Content type
application/json
{
  • "items": [],
  • "totalCount": 1
}

Add trusted search page URI

Creates a new trusted search page URI entry in a specific Coveo Cloud organization. Any search page whose URI begins with that prefix will be allowed to use the SAML SSO provider of that organization as a means of authentication.
Notes:

  • No URI is trusted by default.
  • Creating a trusted search page URI entry with the empty string will result in all URIs being trusted, which is not recommended.
    Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Request Body schema: application/json
required

The trusted search page URI information.

required
object
uriPrefix
required
string

The URI to trust. Any search page whose URI begins with this prefix will be trusted by the target Coveo Cloud organization.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "trustedUri": {}
}

List recently seen search page URIs that were not trusted.

Lists URI that were recently seen during SSO but that were not trusted. The last 100 URI are kept for 7 days.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

query Parameters
page
integer <int32> >= 0
Default: 0

The 0-based number of the page of results to get.

perPage
integer <int32> [ 0 .. 200 ]
Default: 20

The number of results to include per page.

Responses

Response samples

Content type
application/json
{}

Delete trusted search page URI

Removes a trusted search page URI entry from a specific Coveo Cloud organization.

Privilege(s) required
{"level":"NORMAL","owner":"SEARCH_API","targetDomain":"AUTHENTICATION_EDITOR","type":"ENABLE","targetId":"*"}
Authorizations:
oauth2
path Parameters
id
required
string

The unique identifier of the trusted search page URI entry to delete.

organizationId
required
string

The unique identifier of the target Coveo Cloud organization.

Responses

Response samples

Content type
application/json
"string"