openapi: 3.0.1
info:
title: Usage Analytics Write API
description: The [Coveo Cloud](https://docs.coveo.com/en/186/) [Usage Analytics](https://docs.coveo.com/en/182/) Write API
service allows you to log all end-user interactions with search interfaces and optionally other interfaces such as support
case creation interfaces or your [indexed](https://docs.coveo.com/en/204/) web sites.
version: '1.0'
servers:
- url: https://analytics.cloud.coveo.com/rest/ua
description: Coveo public API endpoint
security:
- v8:
- full
tags:
- name: Analytics API - Version 14
- name: Analytics API - Version 15
paths:
/v14/analytics/click:
post:
tags:
- Analytics API - Version 14
summary: Adds a Click Event via POST
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: post__v14_analytics_click
parameters:
- name: visitor
in: cookie
description: The unique identifier of the visitor. If not provided, a new identifier will be created and returned
as a HTTP cookie.
deprecated: true
schema:
type: string
requestBody:
description: The click event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/ClickEventModelV14'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddClickEventResponseV14'
deprecated: true
/v14/analytics/custom:
post:
tags:
- Analytics API - Version 14
summary: Adds a Custom Event via POST
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: post__v14_analytics_custom
parameters:
- name: visitor
in: cookie
description: The unique identifier of the visitor. If not provided, a new identifier will be created and returned
as a HTTP cookie.
deprecated: true
schema:
type: string
requestBody:
description: The custom event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomEventModelV14'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddCustomEventResponseV14'
deprecated: true
/v14/analytics/search:
post:
tags:
- Analytics API - Version 14
summary: Adds a Search Event via POST
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: post__v14_analytics_search
parameters:
- name: visitor
in: cookie
description: The unique identifier of the visitor. If not provided, a new identifier will be created and returned
as a HTTP cookie.
deprecated: true
schema:
type: string
requestBody:
description: The search event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchEventModelV14'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddSearchEventResponseV14'
deprecated: true
/v14/analytics/searches:
post:
tags:
- Analytics API - Version 14
summary: Adds Multiple Search Events via POST
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: post__v14_analytics_searches
parameters:
- name: visitor
in: cookie
description: The unique identifier of the visitor. If not provided, a new identifier will be created and returned
as a HTTP cookie.
deprecated: true
schema:
type: string
requestBody:
description: The search events to add. Please note that that the clientId from the first search event will be used
to compute the visit.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SearchEventModelV14'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AddSearchEventResponseV14'
deprecated: true
/v14/analytics/monitoring/health:
get:
tags:
- Analytics API - Version 14
summary: Health Check for the Analytics Service
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: get__v14_analytics_monitoring_health
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
deprecated: true
/v14/analytics/status:
get:
tags:
- Analytics API - Version 14
summary: Gets the Status of the Analytics Service
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: get__v14_analytics_status
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
deprecated: true
/v14/analytics/visit:
get:
tags:
- Analytics API - Version 14
summary: Get the User Current Visit Informations
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: get__v14_analytics_visit
parameters:
- name: user
in: query
description: The unique identifier of the user performing the search event. If not provided, the username will be
extracted from the token.
schema:
type: string
- name: visitor
in: cookie
description: The unique identifier of the visitor. If not provided, a new identifier will be created and returned
as a HTTP cookie.
deprecated: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VisitInfoResponseV14'
deprecated: true
delete:
tags:
- Analytics API - Version 14
summary: Clears All Cookies Associated with This API
description: This endpoint is deprecated and will be removed on October 1st, 2024.
operationId: delete__v14_analytics_visit
responses:
default:
description: default response
content:
application/json: {}
deprecated: true
/v15/analytics/click:
post:
tags:
- Analytics API - Version 15
summary: Log Click Event via POST
description: Logs a click event. Typically, when the end-user opens or previews a result, the search interface logs
a click event.
operationId: post__v15_analytics_click
parameters:
- name: org
in: query
description: The name of the organization (Coveo Cloud V2 only)
schema:
type: string
- name: visitor
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. The unique identifier of the visitor. Unless `prioritizeVisitorParameter` is
set to `true`, the service automatically attempts to override this query string parameter with the visitor cookie.
If no `visitor` parameter is provided and the visitor cookie is absent, a new identifier is created and returned
as the `visitorId` property in the response body, and as a visitor cookie.'
deprecated: true
schema:
type: string
- name: prioritizeVisitorParameter
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. Whether to force the service to use the provided `visitor` query string parameter,
rather than automatically attempting to override this parameter with the visitor cookie.'
deprecated: true
schema:
type: boolean
default: false
requestBody:
description: The click event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/ClickEventModelV15'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddClickEventResponseV15'
/v15/analytics/custom:
post:
tags:
- Analytics API - Version 15
summary: Log Custom Event via POST
description: Logs a custom event. Typically, when the end-user interacts with a page in a way that needs to be recorded,
but that is neither a search, a click, or a view event (e.g., toggling the result list layout, changing end-user preferences),
the page logs a custom event.
operationId: post__v15_analytics_custom
parameters:
- name: org
in: query
description: The name of the organization (Coveo Cloud V2 only)
schema:
type: string
- name: visitor
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. The unique identifier of the visitor. Unless `prioritizeVisitorParameter` is
set to `true`, the service automatically attempts to override this query string parameter with the visitor cookie.
If no `visitor` parameter is provided and the visitor cookie is absent, a new identifier is created and returned
as the `visitorId` property in the response body, and as a visitor cookie.'
deprecated: true
schema:
type: string
- name: prioritizeVisitorParameter
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. Whether to force the service to use the provided `visitor` query string parameter,
rather than automatically attempting to override this parameter with the visitor cookie.'
deprecated: true
schema:
type: boolean
default: false
requestBody:
description: The custom event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomEventModelV15'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddCustomEventResponseV15'
/v15/analytics/search:
post:
tags:
- Analytics API - Version 15
summary: Log Search Event via POST
description: Logs a search event. Typically, when an end-user interacts with a search interface in a way that triggers
a [query](https://docs.coveo.com/en/231/glossary/query) to the [Search API](https://docs.coveo.com/en/52/cloud-v2-developers/search-api)
(e.g., submitting a query from the search box, selecting a [facet](https://docs.coveo.com/en/198/glossary/facet) value,
etc.), the search interface logs a search event.
operationId: post__v15_analytics_search
parameters:
- name: org
in: query
description: The name of the organization (Coveo Cloud V2 only)
schema:
type: string
- name: visitor
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. The unique identifier of the visitor. Unless `prioritizeVisitorParameter` is
set to `true`, the service automatically attempts to override this query string parameter with the visitor cookie.
If no `visitor` parameter is provided and the visitor cookie is absent, a new identifier is created and returned
as the `visitorId` property in the response body, and as a visitor cookie.'
deprecated: true
schema:
type: string
- name: prioritizeVisitorParameter
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. Whether to force the service to use the provided `visitor` query string parameter,
rather than automatically attempting to override this parameter with the visitor cookie.'
deprecated: true
schema:
type: boolean
default: false
requestBody:
description: The search event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchEventModelV15'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddSearchEventResponseV15'
/v15/analytics/searches:
post:
tags:
- Analytics API - Version 15
summary: Log Search Event Batch via POST
description: Logs one or more search events. Typically, when an end-user interacts with a search interface in a way
that triggers a [query](https://docs.coveo.com/en/231/glossary/query) to the [Search API](https://docs.coveo.com/en/52/cloud-v2-developers/search-api)
(e.g., submitting a query from the search box, selecting a [facet](https://docs.coveo.com/en/198/glossary/facet) value,
etc.), the search interface logs a search event. Logging a batch of more than three items should generally be avoided,
due to possible timing issues (e.g., all items in a batch inherit the same datetime).
operationId: post__v15_analytics_searches
parameters:
- name: org
in: query
description: The name of the organization (Coveo Cloud V2 only)
schema:
type: string
- name: visitor
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. The unique identifier of the visitor. Unless `prioritizeVisitorParameter` is
set to `true`, the service automatically attempts to override this query string parameter with the visitor cookie.
If no `visitor` parameter is provided and the visitor cookie is absent, a new identifier is created and returned
as the `visitorId` property in the response body, and as a visitor cookie.'
schema:
type: string
- name: prioritizeVisitorParameter
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. Whether to force the service to use the provided `visitor` query string parameter,
rather than automatically attempting to override this parameter with the visitor cookie.'
deprecated: true
schema:
type: boolean
default: false
requestBody:
description: The search events to add.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SearchEventModelV15'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AddSearchEventResponseV15'
/v15/analytics/view:
post:
tags:
- Analytics API - Version 15
summary: Log View Event via POST
description: Logs a view event. Although view events are not currently available for usage analytics reports, they are
required to feed [Coveo Machine Learning](https://docs.coveo.com/en/188/glossary/coveo-machine-learning) [event recommendations](https://docs.coveo.com/en/1016/glossary/event-recommendations)
[models](https://docs.coveo.com/en/1012/glossary/model). A page corresponding to an [item](https://docs.coveo.com/en/210/glossary/item)
which should be considered as a possible candidate result for the output of a Coveo Machine Learning event recommendation
model must log a view event on its own whenever it is navigated to.
operationId: post__v15_analytics_view
parameters:
- name: org
in: query
description: The name of the organization (Coveo Cloud V2 only)
schema:
type: string
- name: visitor
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. The unique identifier of the visitor. Unless `prioritizeVisitorParameter` is
set to `true`, the service automatically attempts to override this query string parameter with the visitor cookie.
If no `visitor` parameter is provided and the visitor cookie is absent, a new identifier is created and returned
as the `visitorId` property in the response body, and as a visitor cookie.'
deprecated: true
schema:
type: string
- name: prioritizeVisitorParameter
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. Whether to force the service to use the provided `visitor` query string parameter,
rather than automatically attempting to override this parameter with the visitor cookie.'
deprecated: true
schema:
type: boolean
default: false
requestBody:
description: The view event to add.
content:
application/json:
schema:
$ref: '#/components/schemas/ViewEventModelV15'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddViewEventResponseV15'
/v15/analytics/collect:
post:
tags:
- Analytics API - Version 15
summary: Collect GA-Style Events
operationId: post__v15_analytics_collect
parameters: []
requestBody:
description: The event in JSON based on https://docs.coveo.com/en/l41i0031/build-a-search-ui/measurement-protocol-parameter-reference
content:
application/json:
schema:
type: object
additionalProperties:
type: object
required: true
responses:
default:
description: default response
content:
application/json: {}
/v15/analytics/monitoring/health:
get:
tags:
- Analytics API - Version 15
summary: Get Service Status
description: Returns the status of the Usage Analytics Write service. Possible values are 'UP', 'unavailable' and 'degraded'.
operationId: get__v15_analytics_monitoring_health
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
/v15/analytics/status:
get:
tags:
- Analytics API - Version 15
summary: Get Service Status
description: This endpoint is exposed for backward compatibility reasons. Use `monitoring/health` instead. Returns the
status of the Usage Analytics Write service. Possible values are 'online', 'unavailable' and 'degraded'.
operationId: get__v15_analytics_status
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
/v15/analytics/visit:
get:
tags:
- Analytics API - Version 15
summary: Get Current Visit
description: Returns the current `visitId`, `visitorId` and `clientId`.
operationId: get__v15_analytics_visit
parameters:
- name: user
in: query
description: The unique identifier of the user performing the search event. If not provided, the username will be
extracted from the token.
schema:
type: string
- name: org
in: query
description: The name of the organization (Coveo Cloud V2 only)
schema:
type: string
- name: visitor
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. The unique identifier of the visitor. Unless `prioritizeVisitorParameter` is
set to `true`, the service automatically attempts to override this query string parameter with the visitor cookie.
If no `visitor` parameter is provided and the visitor cookie is absent, a new identifier is created and returned
as the `visitorId` property in the response body, and as a visitor cookie.'
deprecated: true
schema:
type: string
- name: clientId
in: query
description: The unique identifier of the visitor. If a client id is provided, it is prioritized over any value passed
for the visitor id parameter.
schema:
type: string
- name: prioritizeVisitorParameter
in: query
description: '''''''DEPRECATED'''''' The `clientId` parameter should be used instead of `visitorId` in the event payload
to capture the visitor identifier. Whether to force the service to use the provided `visitor` query string parameter,
rather than automatically attempting to override this parameter with the visitor cookie.'
deprecated: true
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/VisitInfoResponseV15'
delete:
tags:
- Analytics API - Version 15
summary: Delete Visit Cookie
description: Deletes the current `visitorId` cookie. A new one will be generated during the next interaction with the
service, which will also create a new `visitId`.
operationId: delete__v15_analytics_visit
responses:
default:
description: default response
content:
application/json: {}
components:
schemas:
AddClickEventResponseV14:
type: object
properties:
visitId:
type: string
description: The ID of the visit associated with the provided click event
visitorId:
type: string
description: Unique identifier associated with the current visitor. See [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random%29)>)
example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
clientId:
type: string
description: Unique identifier associated with the current logged user. See [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random%29)>)
example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
description: The response to add click event operation
ClickEventModelV14:
required:
- actionCause
- collectionName
- documentPosition
- documentUriHash
- language
- originLevel1
- originLevel2
- searchQueryUid
- sourceName
type: object
properties:
language:
type: string
description: The language that end user is using. Use ISO 639-1 codes. See <a href=http://en.wikipedia.org/wiki/ISO_639-1>ISO
639-1</a> for more information
userAgent:
type: string
description: The user agent string of the end user's browser. See <a href=http://en.wikipedia.org/wiki/User_agent>User
Agent</a> for more information.
customData:
type: object
additionalProperties:
type: object
description: Custom data that can contain all the user defined dimensions and their values. Keys can only contain
alphanumeric or underscore characters. Spaces in the key are converted to underscores. Uppercase characters
in the key are converted to lowercase characters. It is highly recommended that you create your custom dimension
before adding customData
description: Custom data that can contain all the user defined dimensions and their values. Keys can only contain
alphanumeric or underscore characters. Spaces in the key are converted to underscores. Uppercase characters in
the key are converted to lowercase characters. It is highly recommended that you create your custom dimension
before adding customData
anonymous:
type: boolean
description: Indicates if the user is anonymous.
username:
type: string
description: The unique identifier of the user performing the search event. If not provided, the username will be
extracted from the token.
userDisplayName:
type: string
description: The display name of the user performing the search event.
splitTestRunName:
type: string
description: The name of the A/B test run, if one is active.
splitTestRunVersion:
type: string
description: The version of the A/B test run, if one is active.
originLevel1:
type: string
description: The origin this event took place
originLevel2:
type: string
description: The origin this event took place
originLevel3:
type: string
description: The origin this event took place
device:
type: string
description: The name of the device that the end user is using
deprecated: true
mobile:
type: boolean
description: Whether the end user's device is a mobile device or not
deprecated: true
documentUri:
type: string
description: The @sysuri of the document that was clicked
deprecated: true
documentUriHash:
type: string
description: The @sysurihash of the document that was clicked
searchQueryUid:
type: string
description: The searchQueryUid of the search that returned the document that was clicked. This must be a valid
searchQueryUid that contains the provided documentUri and documentUriHash.
collectionName:
type: string
description: The @syscollection of the document that was clicked
sourceName:
type: string
description: The @syssource of the document that was clicked
documentPosition:
type: integer
description: The position of the document (one-based) that was clicked in the list of resultsThis number must take
into consideration pagination settings. If the pages contain ten results each, the third document of the second
page is at the position 22.
format: int32
actionCause:
type: string
description: 'The type of operation that triggered this event. Example: ''firstSearch'', ''searchEnter'''
documentTitle:
type: string
description: The title of the document that was clicked.
documentUrl:
type: string
description: The URL of the document that was clicked.
queryPipeline:
type: string
description: The query pipeline of the search that returned the document that was clicked.
rankingModifier:
type: string
description: The ranking modifier that affected the clicked document.
description: An event that represents a result that was clicked
AddCustomEventResponseV14:
type: object
properties:
visitId:
type: string
description: The ID of the visit associated with the provided custom event
visitorId:
type: string
description: Unique identifier associated with the current visitor. See [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random%29)>)
example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
clientId:
type: string
description: Unique identifier associated with the current logged user. See [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random%29)>)
example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
description: The response to add custom event operation
CustomEventModelV14:
required:
- eventType
- eventValue
- language
- originLevel1
- originLevel2
type: object
properties:
language:
type: string
description: The language that end user is using. Use ISO 639-1 codes. See <a href=http://en.wikipedia.org/wiki/ISO_639-1>ISO
639-1</a> for more information
userAgent:
type: string
description: The user agent string of the end user's browser. See <a href=http://en.wikipedia.org/wiki/User_agent>User
Agent</a> for more information.
customData:
type: object
additionalProperties:
type: object
description: Custom data that can contain all the user defined dimensions and their values. Keys can only contain
alphanumeric or underscore characters. Spaces in the key are converted to underscores. Uppercase characters
in the key are converted to lowercase characters. It is highly recommended that you create your custom dimension
before adding customData
description: Custom data that can contain all the user defined dimensions and their values. Keys can only contain
alphanumeric or underscore characters. Spaces in the key are converted to underscores. Uppercase characters in
the key are converted to lowercase characters. It is highly recommended that you create your custom dimension
before adding customData
anonymous:
type: boolean
description: Indicates if the user is anonymous.
username:
type: string
description: The unique identifier of the user performing the search event. If not provided, the username will be
extracted from the token.
userDisplayName:
type: string
description: The display name of the user performing the search event.
splitTestRunName:
type: string
description: The name of the A/B test run, if one is active.
splitTestRunVersion:
type: string
description: The version of the A/B test run, if one is active.
originLevel1:
type: string
description: The origin this event took place
originLevel2:
type: string
description: The origin this event took place
originLevel3:
type: string
description: The origin this event took place
device:
type: string
description: The name of the device that the end user is using
deprecated: true
mobile:
type: boolean
description: Whether the end user's device is a mobile device or not
deprecated: true
eventType:
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coveo/refs/heads/main/openapi/coveo-usage-analytics-write-openapi-original.yml