openapi: 3.0.1
info:
title: Coveo Activity Activities Answer API
description: API for Coveo Platform
termsOfService: https://www.coveo.com/en/support/terms-agreements
contact:
name: Coveo
url: https://connect.coveo.com/s/discussions
version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
description: Coveo public API endpoint
security:
- oauth2:
- full
tags:
- name: Answer
x-displayName: Answer
paths:
/rest/organizations/{organizationId}/answer/v1/configs/{configId}/generate:
post:
tags:
- Answer
summary: Get Answer
description: Get an answer for a question
operationId: getAnswer
parameters:
- $ref: '#/components/parameters/OrganizationIdPath'
- $ref: '#/components/parameters/ConfigIdPath'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnswerSearchRequest'
responses:
'200':
description: OK
content:
text/event-stream:
schema:
$ref: '#/components/schemas/GenQAResponse'
examples:
HeaderMessage:
$ref: '#/components/examples/HeaderMessage'
AnswerMessage:
$ref: '#/components/examples/AnswerMessage'
CitationsMessage:
$ref: '#/components/examples/CitationsMessage'
EndOfStreamMessage:
$ref: '#/components/examples/EndOfStreamMessage'
security:
- oauth2:
- full
components:
schemas:
AnalyticsRequestParameters:
type: object
nullable: true
properties:
capture:
type: boolean
description: '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](docs.coveo.com/en/1389)).'
trackingId:
type: string
description: A value to identify which web property an event is related to.
userId:
type: string
description: The ID of the user who is currently logged in. If not present, this ID is obtained from the authentication token.
clientId:
type: string
description: '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](https://docs.coveo.com/en/masb0234/) 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](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)>)-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`.'
documentLocation:
type: string
description: 'The URL of the current page or component.
If not present, the referrer is obtained from the [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header.
**Note**: This information can be obtained from `coveo.analytics.js`.'
documentReferrer:
type: string
description: '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`.'
pageId:
description: 'A GUID representing the page ID.
**Note**: This information can be obtained from `coveo.analytics.js`.'
anyOf:
- type: string
nullable: true
- type: integer
userIp:
type: string
description: 'The user IP. If not present, the IP is obtained from the [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) and [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) headers.
**Note**: This information is required when endpoints are behind a proxy.
**Example**: `127.0. 0.1`'
clientRequestId:
type: string
description: '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:
type: string
description: Client ISO 8601 timestamp with milliseconds.
userAgent:
type: string
description: 'The user agent of the request. If not present, the user agent is obtained from the [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) header.
**Note**: This information is required when endpoints are behind a proxy.'
actionCause:
type: string
description: 'The type of operation that triggered this event.
See [Standard actions and Usage Analytics reference](docs.coveo.com/en/1389)).'
example: facetSelect
originContext:
type: string
example: CommunitySearch
description: 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
customData:
type: object
description: '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'
configId:
type: string
description: 'An optional external reference to a use-case specific search configuration.
These configurations are maintained by LOBs and the search api has no knowledge of them.
This field can be used by LOBs to break down search statistics in LOB specific reporting.
This field is not present on non-captured search calls.'
source:
description: Defines one or more client side libraries that generated the analytics event. The format should be the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
type: array
items:
type: string
x-coveo-internal: true
commerce:
type: object
description: Commerce specific search context
x-coveo-internal: true
required:
- country
- currency
properties:
country:
type: string
nullable: true
example: US
description: The country of the storefront in ISO 3166 — Country Codes format.
currency:
type: string
nullable: true
example: USD
description: The selected currency of the cart and transactions.
Locale:
type: string
nullable: true
description: 'The locale of the current user. Must comply with IETF''s [BCP 47](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) 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`).
'
example: en-US
AnswerSearchRequest:
type: object
properties:
q:
type: string
description: '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.
'
example: Coveo "Cloud V2" platform
aq:
type: string
description: '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).
'
example: '@year==2017'
cq:
type: string
description: '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.
'
example: '@documenttype==forumpost'
lq:
type: string
description: '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).
'
example: '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.
'
queryCorrection:
type: object
required:
- enabled
description: "This parameter controls the behavior of the Coveo query correction feature.\n\nOnce enabled, this feature will:\n - Attempt to correct your query if it doesn't return enough results.\n - If corrections are found, the API will automatically correct your query.\n\nQuery corrections are derived from the index's _Did You Mean_ feature and ML query corrections.\n\nCorrection information will be returned in the `queryCorrection` property of the response. It will contain:\n - The original query if it was automatically corrected.\n - The corrected query if it was automatically corrected.\n - A list of wordCorrections generated by our system.\n\nThis feature is off by default.\n"
properties:
enabled:
type: boolean
description: 'Whether or not this feature should be enabled. If it''s set to false, other `queryCorrection` properties will be ignored.
'
options:
type: object
properties:
automaticallyCorrect:
type: string
enum:
- never
- whenNoResults
default: whenNoResults
description: "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:\n\n - applying keyword corrections, if any were provided by the _Did You Mean_ index feature, or otherwise\n - replacing the original `q` value with the highest ranked Coveo ML query suggestion that will return results.\n\nIf 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.\n"
maximumAge:
$ref: '#/components/schemas/MaximumAge'
pipeline:
$ref: '#/components/schemas/Pipeline'
searchHub:
$ref: '#/components/schemas/SearchHub'
tab:
$ref: '#/components/schemas/Tab'
context:
$ref: '#/components/schemas/Context'
locale:
$ref: '#/components/schemas/Locale'
timezone:
$ref: '#/components/schemas/Timezone'
analytics:
$ref: '#/components/schemas/AnalyticsRequestParameters'
partialMatch:
type: boolean
description: '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.
**Default:** `false`
'
example: true
default: false
partialMatchKeywords:
type: integer
description: 'The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.
**Default:** `5`
'
format: int32
example: 4
default: 5
partialMatchThreshold:
type: string
description: 'An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.
**Default:** `50%`
'
example: 75%
default: 50%
lqPartialMatchMaxKeywords:
type: integer
description: 'The maximum number of keywords from the large query expression that will be included in the partial match expression.
**Default:** `100`
'
format: int32
example: 20
default: 100
lqPartialMatchKeywords:
type: integer
description: 'The minimum number of keywords that need to be present in the large query expression to convert it to a partial match expression.
**Default:** `5`
'
format: int32
example: 4
default: 5
lqPartialMatchThreshold:
type: string
description: 'An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression.
**Default:** `50%`
'
example: 75%
default: 50%
wildcards:
type: boolean
description: 'Whether to enable the *wildcards* feature of the index in order to expand basic expression keywords containing wildcard characters (`*`).
**Default:** `false`
'
example: true
default: false
questionMark:
type: boolean
description: 'Whether to enable question mark characters (`?`) in the *wildcards* feature of the index.
**Note:** Setting this parameter to `true` has no effect unless you also set the `wildcards` parameter to `true`.
**Default:** `false`
'
example: true
default: false
enableQuerySyntax:
type: boolean
description: 'Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression.
**Default:** `true`
'
example: true
default: true
facets:
type: array
description: The facet operations to perform on the query results.
items:
type: object
additionalProperties: true
facetOptions:
type: object
description: Options for configuring how facets are reordered.
properties:
freezeFacetOrder:
type: boolean
description: '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`
'
enableIndexFacetOrdering:
type: boolean
description: '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`
'
categoryFacets:
type: array
description: Hierarchical facet requests.
items:
type: object
additionalProperties: true
referrer:
$ref: '#/components/schemas/Referrer'
actionsHistory:
type: array
description: <p>The previous query and page view actions made by the current user.</p> <p>Coveo Machine Learning Content Recommendation models use this information to provide contextually relevant output.</p> <p><strong>Note:</strong> Page view actions are typically populated by the <a href="https://github.com/coveo/coveo.analytics.js">coveo.analytics.js</a> script.</p>
items:
$ref: '#/components/schemas/ActionHistory'
example:
- name: Query
value: Machine learning powered search
time: '2017-08-16T11:33:29.427Z'
- name: PageView
value: http://www.example.com/
time: '2017-08-15T17:34:08.398Z'
mlParameters:
$ref: '#/components/schemas/MlParameters'
pipelineRuleParameters:
$ref: '#/components/schemas/PipelineRuleParameters'
Timezone:
type: string
nullable: true
description: 'The [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 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.
'
example: America/New_York
Tab:
type: string
nullable: true
description: '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.
'
example: ForumTab
SearchHub:
type: string
nullable: true
description: '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](https://docs.coveo.com/en/56/) that enforces a specific [`pipeline`](https://docs.coveo.com/en/56/#pipeline-string-optional), or a [`searchHub`](https://docs.coveo.com/en/56/#searchhub-string-optional) 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.
'
example: CustomerPortal
GenQAResponse:
type: object
required:
- payloadType
- payload
properties:
payloadType:
type: string
description: Type of the contained GenQA payload (e.g., genqa.headerMessageType).
payload:
type: string
format: json
description: JSON-encoded string containing the actual message payload.
finishReason:
type: string
nullable: true
enum:
- COMPLETED
- ERROR
description: Reason for stream termination, if applicable.
errorMessage:
type: string
nullable: true
description: Error message if the stream failed.
statusCode:
type: integer
nullable: true
description: HTTP status code associated with the message, if applicable.
Referrer:
type: string
nullable: true
description: '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.
'
example: http://www.example.com/
MaximumAge:
type: integer
nullable: true
description: '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)'
format: int32
example: 1800000
default: -1
MlParameters:
type: object
nullable: true
description: '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"}`
'
example:
num: 3
padding: trending
PipelineRuleParameters:
type: object
nullable: true
additionalProperties: true
maxProperties: 255
description: "This defines generic parameters to be used by rules.\nIt defines the \"scopes\", or in other words, the rules in which the parameters should be used.\nThe generic parameters are defined within a particular scope and are only be accessible inside of it.\nThis is a read-only parameter, so its value will not be overridden.\n\n`{\n \"scope\": {\n \"parameterName\" : \"parameterValue\"\n }\n}`\n\nWhile using Gen AI, if additional document fields are required for the resulting\ncitations, these fields can be specified through the 'citationsFieldToInclude'\nproperty of the 'mlGenerativeQuestionAnswering' scope.\n\n> **Note:**\n> Getting dictionary fields for citations is not supported.\n\n**Examples:**\n- `{\"mlGenerativeQuestionAnswering\": { \"responseFormat\": { \"answerStyle\": \"bullet\" } } }`\n- `{\"mlGenerativeQuestionAnswering\": { \"citationsFieldToInclude\": [\"field1\", \"field2\"] } }`\n\nMax Size: 1KB\n"
example:
genqa:
responseFormat:
answerStyle: bullet
ActionHistory:
required:
- name
- time
type: object
properties:
name:
type: string
description: 'The action history event name.
Possible values:
- **Query**
- **PageView**'
example: PageView
value:
type: string
description: The action history value, which is either a query expression or a page URI, depending on the action history event `name`.
time:
type: string
description: The time when the action history event was sent from the client.
Pipeline:
type: string
nullable: true
description: '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](https://docs.coveo.com/en/56/) that enforces a specific [`pipeline`](https://docs.coveo.com/en/56/#pipeline-string-optional), or a [`searchHub`](https://docs.coveo.com/en/56/#searchhub-string-optional) 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 `pipeline` value of the query (or to the `"default"` string, if no `pipeline` value was specified in the query).
See also [Managing Query Pipelines](https://docs.coveo.com/en/1450/).
'
example: CustomerQueryPipeline
Context:
type: object
nullable: true
additionalProperties: true
description: '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"]}`'
examples:
HeaderMessage:
summary: Header
description: "This is the decoded content of the `payload`:\n\n```json\n{\n \"answerStyle\": \"default\",\n \"contentFormat\": \"text/markdown\"\n}\n```\n"
value:
payloadType: genqa.headerMessageType
payload: JSON omitted for readability. See description above.
finishReason: null
errorMessage: null
statusCode: null
CitationsMessage:
summary: Citations
description: "This is the decoded content of the `payload`:\n\n```javascript\n{\n \"citations\": [\n {\n \"id\": \"abc123\", // The unique citation ID. Required.\n \"title\": \"Coveo Search Best Practices\", // The item title. It may be empty. Required.\n \"uri\": \"https://example.com/docs/search\", // The item URI. Required.\n \"permanentid\": \"xyz789\", // The item permanent ID. Required.\n \"clickUri\": \"https://example.com/docs/search\", // The item click URI. Required.\n \"text\": \"This document describes best practices\", // The item excerpt. Required.\n \"fields\": {\n \"urihash\": \"def456
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coveo/refs/heads/main/openapi/coveo-answer-api-openapi.yml