Coveo Analytics API - Version 15 API

openapi: 3.2.0
info:
  title: Usage Analytics Write Analytics API - Version 15 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 15
paths:
  /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:
    ClickEventModelV15:
      required:
      - actionCause
      - documentPosition
      - language
      - searchQueryUid
      - sourceName
      type: object
      properties:
        language:
          type: string
          description: (Required, except when logging View events). The language of the end-user. Must be a valid [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) code
          example: en
        userAgent:
          type: string
          description: Information about the browser and operating system of the end-user who caused the search interface to log an event. See [User Agent](http://en.wikipedia.org/wiki/User_agent) for more information
          example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3249.481 Safari/537.36
        customData:
          type: object
          additionalProperties:
            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
          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
        anonymous:
          type: boolean
          description: Whether the interaction that caused the search interface to log the event was triggered by an anonymous user. If set to `true`, the Usage Analytics Write API will not extract the name and `userDisplayName`, if present, from the search token
          example: false
        username:
          type: string
          description: The name of the user security identity who caused the search interface to log the event. Can only be specified when authenticated with a token with **impersonate** privilege. If unspecified and the request is authenticated with a search token, the service attempts to extract the username value from the access token that authenticated the request. If this fails, the username value is left blank. If unspecified and the request is authenticated with an API key, `username` is set to `anonymous`
          example: alice.smith@example.com
        userDisplayName:
          type: string
          description: The display name of the user performing the event. Can only be specified when authenticated with a token with **impersonate** privilege. If unspecified and the request is authenticated with a search token, the service attempts to extract the `userdisplayName` value from the access token that authenticated the request
          example: Alice
        splitTestRunName:
          type: string
          description: The name of the A/B test run, if one is active. See [Managing A/B Tests](https://docs.coveo.com/en/3255/)
          example: splitTest
        splitTestRunVersion:
          type: string
          description: The version of the A/B test run, if one is active
          example: splitTestRunAlpha
        originLevel1:
          type: string
          description: The name/identifier of the search interface from which the event originates. If unspecified and the request is authenticated with a search token, the service attempts to extract the `searchHub` value from the access token that authenticated the request
          example: ExternalSearch
        originLevel2:
          type: string
          description: The name/identifier of the tab from which the event originates
          example: all
        originLevel3:
          type: string
          description: The URL of the page that redirected the browser to the search interface from which the event originates, i.e. `document.referrer`
          example: https://docs.coveo.com/en/0/coveo-documentation-for-developers
        outcome:
          type: integer
          description: An indication of how good the outcome of this event is. A value of `-5` corresponds to the worst possible outcome, a value of `0` corresponds to a neutral outcome, and a value of `5` corresponds to the best possible outcome
          format: int32
          example: 0
        originContext:
          type: string
          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
          example: CommunitySearch
        clientId:
          type: string
          description: A value that uniquely identifies the user who is logging the event. Must be a valid UUID.
          example: 489aa3e3-aed2-4563-8e81-62bb73178a56
        trackingId:
          type: string
          description: A value to identify which web property an event is related to. This can only contain lowercase letters, numbers, and underscores (`_`).
          example: online_store
        documentUri:
          type: string
          description: The `@uri` of the item that was clicked
          example: https://docs.coveo.com/en/1243/
          deprecated: true
        documentUriHash:
          type: string
          description: The `@urihash` of the item that was clicked. Deprecated, please use customData.contentIdValue instead.
          example: xyhvGJJGRDM3OiG5
          deprecated: true
        searchQueryUid:
          type: string
          description: The unique identifier of the event which led the search interface to log the click event. It is recommend to use the `searchUid` in the response of the corresponding search request to the Search API, or any [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random%29)>) of length less than or equal to 36 characters. UUIDs longer than 36 characters are truncated by the service. This must be a valid searchQueryUid for an event that contains the provided documentUri and documentUriHash.
          example: df60b2fb-c276-49ae-b704-2ee45609f3a6
        collectionName:
          type: string
          description: The `@syscollection` of the item that was clicked
          example: Default
        sourceName:
          type: string
          description: The `@source` of the item that was clicked
          example: AnswersCloud
        documentPosition:
          type: integer
          description: The 1-based index position of the item that was clicked in the result list. This number must take into consideration pagination settings. If the pages contain ten results each, the third item of the second page is at the position 23.
          format: int32
          example: 1
        actionCause:
          type: string
          description: The type of operation that triggered this event (see [`analyticsActionCauseList`](https://github.com/coveo/search-ui/blob/master/src/ui/Analytics/AnalyticsActionListMeta.ts#L213)
          example: documentOpen
        documentTitle:
          type: string
          description: The title of the item that was clicked
          example: Coveo for Salesforce
        documentUrl:
          type: string
          description: The URL of the item that was clicked
          example: https://docs.coveo.com/en/1243/
        documentAuthor:
          type: string
          description: The author of the item that was clicked
          example: John Doe
        queryPipeline:
          type: string
          description: The name of the query pipeline which processed the query that led to the click event. When unspecified, the service uses the [`pipeline`](https://docs.coveo.com/en/56/#pipeline-string-optional) value set in the search token, if any
          example: External Search
        rankingModifier:
          type: string
          description: The ranking modifier that affected the clicked item
          example: Reveal ART
        documentCategory:
          type: string
          description: The category of the clicked item
          example: KBSupport
      description: An event that represents a result that was clicked
    FacetStateModelV15:
      required:
      - facetType
      - field
      - id
      - state
      - value
      type: object
      properties:
        field:
          type: string
          description: The facet field
          example: productcategory
        id:
          type: string
          description: The unique identifier of the facet in the search interface. Must match ^[a-zA-Z0-9@\-_]{1,60}$
          example: productcategory1
        value:
          type: string
          description: The name of the facet value
          example: laptop
        valuePosition:
          type: integer
          description: The 1-based position of the value in the facet
          format: int32
          example: 2
        displayValue:
          type: string
          description: The display name of the facet value that was interacted with
          example: Laptop
        facetType:
          type: string
          description: The facet data type
          example: specific
        state:
          type: string
          description: The facet action type.
          example: selected
          enum:
          - auto_selected
          - selected
          - excluded
        facetPosition:
          type: integer
          description: The 1-based position of the facet
          format: int32
          example: 1
        title:
          type: string
          description: The facet title
          example: Product Category
      description: The facet state
    SearchEventModelV15:
      required:
      - actionCause
      - language
      - queryText
      - responseTime
      - searchQueryUid
      type: object
      properties:
        language:
          type: string
          description: (Required, except when logging View events). The language of the end-user. Must be a valid [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) code
          example: en
        userAgent:
          type: string
          description: Information about the browser and operating system of the end-user who caused the search interface to log an event. See [User Agent](http://en.wikipedia.org/wiki/User_agent) for more information
          example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3249.481 Safari/537.36
        customData:
          type: object
          additionalProperties:
            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
          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
        anonymous:
          type: boolean
          description: Whether the interaction that caused the search interface to log the event was triggered by an anonymous user. If set to `true`, the Usage Analytics Write API will not extract the name and `userDisplayName`, if present, from the search token
          example: false
        username:
          type: string
          description: The name of the user security identity who caused the search interface to log the event. Can only be specified when authenticated with a token with **impersonate** privilege. If unspecified and the request is authenticated with a search token, the service attempts to extract the username value from the access token that authenticated the request. If this fails, the username value is left blank. If unspecified and the request is authenticated with an API key, `username` is set to `anonymous`
          example: alice.smith@example.com
        userDisplayName:
          type: string
          description: The display name of the user performing the event. Can only be specified when authenticated with a token with **impersonate** privilege. If unspecified and the request is authenticated with a search token, the service attempts to extract the `userdisplayName` value from the access token that authenticated the request
          example: Alice
        splitTestRunName:
          type: string
          description: The name of the A/B test run, if one is active. See [Managing A/B Tests](https://docs.coveo.com/en/3255/)
          example: splitTest
        splitTestRunVersion:
          type: string
          description: The version of the A/B test run, if one is active
          example: splitTestRunAlpha
        originLevel1:
          type: string
          description: The name/identifier of the search interface from which the event originates. If unspecified and the request is authenticated with a search token, the service attempts to extract the `searchHub` value from the access token that authenticated the request
          example: ExternalSearch
        originLevel2:
          type: string
          description: The name/identifier of the tab from which the event originates
          example: all
        originLevel3:
          type: string
          description: The URL of the page that redirected the browser to the search interface from which the event originates, i.e. `document.referrer`
          example: https://docs.coveo.com/en/0/coveo-documentation-for-developers
        outcome:
          type: integer
          description: An indication of how good the outcome of this event is. A value of `-5` corresponds to the worst possible outcome, a value of `0` corresponds to a neutral outcome, and a value of `5` corresponds to the best possible outcome
          format: int32
          example: 0
        originContext:
          type: string
          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
          example: CommunitySearch
        clientId:
          type: string
          description: A value that uniquely identifies the user who is logging the event. Must be a valid UUID.
          example: 489aa3e3-aed2-4563-8e81-62bb73178a56
        trackingId:
          type: string
          description: A value to identify which web property an event is related to. This can only contain lowercase letters, numbers, and underscores (`_`).
          example: online_store
        searchQueryUid:
          type: string
          description: The unique identifier of the event which led the search interface to log the search event. It is recommended to use the `searchUid` in the response of the corresponding search request to the Search API, or any [UUID v4](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random%29)>) of length less than or equal to 36 characters. UUIDs longer than 36 characters are truncated by the service.
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
        queryText:
          type: string
          description: The original basic query expression (`q`) in the corresponding search request
          example: coveo
        actionCause:
          type: string
          description: The type of operation that triggered this event (see [`analyticsActionCauseList`](https://githu

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coveo/refs/heads/main/openapi/coveo-analytics-api-version-15-api-openapi.yml