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]()-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:

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

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

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

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": "", "originLevel2": "" }`. **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\", // The item URI hash. Required.\n \"clickableuri\": \"https://example.com/docs/search\", // The hyperlinkable item URI. Optional.\n \"date\": 1680700000, // The item date (Unix timestamp). Optional.\n \"filetype\": \"html\", // The item file type. Optional.\n \"language\": [\"en\"], // The item language(s). Optional.\n \"objecttype\": \"document\", // The item object type. Optional.\n \"parents\": \"parent-id-123\", // The item parents. Optional.\n \"permanentid\": \"xyz789\", // The item permanent ID. Optional.\n \"size\": 2048, // The item size in bytes. Optional.\n \"source\": \"Documentation\", // The item source. Optional.\n \"sourcetype\": \"Web\" // The item source type. Optional.\n }\n }\n ]\n}\n```\n" value: payloadType: genqa.citationsType payload: JSON omitted for readability. See description above. finishReason: null errorMessage: null statusCode: null AnswerMessage: summary: Answer Content description: "This is the decoded content of the `payload`:\n\n```json\n{\n \"textDelta\": \"This is the next part of the answer.\"\n}\n```\n" value: payloadType: genqa.messageType payload: JSON omitted for readability. See description above. finishReason: null errorMessage: null statusCode: null EndOfStreamMessage: summary: End of stream description: "This is the decoded content of the `payload`:\n\n```json\n{\n \"answerGenerated\": true\n}\n```\n" value: payloadType: genqa.endOfStreamType payload: JSON omitted for readability. See description above. finishReason: completed errorMessage: null statusCode: 200 parameters: ConfigIdPath: name: configId in: path description: The unique identifier of the answer configuration. required: true schema: type: string OrganizationIdPath: name: organizationId in: path description: The unique identifier of the target Coveo Cloud organization. required: true schema: type: string securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize tokenUrl: https://platform.cloud.coveo.com/oauth/token scopes: full: required