Veterans Affairs Unique User Metrics API

openapi: 3.2.0
info:
  version: 1.0.0
  title: VA My Health Unique User Metrics API
  license:
    name: CC0 1.0 Universal
  description: 'The Department of Veterans Affairs My Health APIs. All paths are relative to https://api.va.gov/my_health.

    '
servers:
- url: https://api.va.gov/my_health
security:
- CookieAuth: []
tags:
- name: Unique User Metrics
paths:
  /v1/unique_user_metrics:
    post:
      description: 'Log unique user metrics events for analytics tracking. Accepts multiple events in a single batch operation

        and buffers them for asynchronous processing by a background job.


        This endpoint is used for tracking unique user interactions with MHV Portal features to provide

        opt-out-free analytics that are more accurate than Google Analytics.


        <strong>Asynchronous Processing:</strong> Events are buffered and processed in batches by a background job.

        The response indicates which events were accepted for processing, not whether they are new unique events.

        Duplicate events (same user + event combination) are handled during background processing.


        <strong>Valid Event Names:</strong> Event names must be from the approved registry of valid events.

        See <a href=''https://github.com/department-of-veterans-affairs/vets-api/blob/master/lib/unique_user_events/event_registry.rb''>EventRegistry</a>

        for the complete list. Invalid event names are silently filtered out.

        '
      operationId: log_unique_user_metrics
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./schemas/UniqueUserMetricsRequest.yml
        description: "Array of event names to log for the authenticated user.\n\n<strong>NOTES:</strong>\n<ul>\n  <li>Events are buffered for asynchronous batch processing</li>\n  <li>Event names must be from the approved registry - see <a href='https://github.com/department-of-veterans-affairs/vets-api/blob/master/lib/unique_user_events/event_registry.rb'>EventRegistry</a></li>\n  <li>Invalid event names are silently filtered out</li>\n  <li>Maximum 50 characters per event name</li>\n  <li>At least one event name must be provided</li>\n</ul>\n"
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: ./schemas/UniqueUserMetricsResponse.yml
              example:
                buffered_events: []
          description: OK - No events were buffered (feature disabled or all events were invalid)
        '202':
          content:
            application/json:
              schema:
                $ref: ./schemas/UniqueUserMetricsResponse.yml
              example:
                buffered_events:
                - mhv_landing_page_accessed
                - secure_messaging_accessed
                - prescriptions_accessed
          description: Accepted - Events were accepted and buffered for asynchronous processing
        '400':
          content:
            application/json:
              schema:
                $ref: ./schemas/Errors.yml
          description: Bad Request - Invalid request parameters (missing event_names, not an array, or empty array)
        '401':
          content:
            application/json:
              schema:
                $ref: ./schemas/Errors.yml
          description: Unauthorized
      summary: /v1/unique_user_metrics
      tags:
      - Unique User Metrics
components:
  securitySchemes:
    CookieAuth:
      type: apiKey
      name: api_session
      in: cookie
      description: An authenticated session is established using the Sessions Controller to initiate federated authentication with an external credential provider, after which an API session token is established in the api_session cookie.