Wispr AI Attribution Tracking API

openapi: 3.2.0
info:
  title: Wispr Backend Analytics Attribution Tracking API
  description: Wispr Backend API
  version: 0.5.2
servers:
- url: https://api.wisprflow.ai
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Attribution Tracking
paths:
  /api/v1/attribution/paywall-viewed:
    post:
      tags:
      - Attribution Tracking
      summary: Track Paywall Viewed
      description: 'Track when a user views the paywall/pricing screen.


        This event can be sent multiple times (repeatable) and is deduplicated

        by the timestamp parameter.


        ga4_client_id is optional for native apps (desktop, iOS, Android). If not

        provided, it will be derived from the user_id for cross-device attribution.

        Web clients should provide ga4_client_id from gtag.js cookies.'
      operationId: track_paywall_viewed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaywallViewedRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributionTrackingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyHeaderPatched: []
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AttributionPlatform:
      type: string
      enum:
      - web
      - desktop_mac
      - desktop_windows
      - ios
      - android
      title: AttributionPlatform
      description: 'Valid platforms for attribution event tracking.


        Desktop clients must use specific variants (DESKTOP_MAC, DESKTOP_WINDOWS).'
    AttributionEventName:
      type: string
      enum:
      - usage_milestone_reached
      - first_external_dictation
      - onboarding_completed
      - paywall_viewed
      - begin_checkout
      - purchase
      - lead
      title: AttributionEventName
      description: 'GA4 event names for attribution tracking.


        These map to GA4 Measurement Protocol event names.

        See: https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference


        USAGE_MILESTONE_REACHED is a single event name; individual milestones (words_200,

        words_500, words_2000) are distinguished via the `milestone_name` custom parameter,

        which should be registered as a GA4 custom dimension for reporting.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AttributionTrackingResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the event was tracked successfully
        event_name:
          $ref: '#/components/schemas/AttributionEventName'
          description: Name of the tracked event
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Additional message
      type: object
      required:
      - success
      - event_name
      title: AttributionTrackingResponse
      description: Response for attribution tracking endpoints.
    PaywallViewedRequest:
      properties:
        ga4_client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ga4 Client Id
          description: GA4 client_id (optional for native apps)
        platform:
          $ref: '#/components/schemas/AttributionPlatform'
          description: Platform where the event originated
        timestamp:
          type: integer
          title: Timestamp
          description: Unix timestamp when paywall was viewed
        user_data:
          anyOf:
          - $ref: '#/components/schemas/AttributionUserData'
          - type: 'null'
          description: Optional user data for enhanced conversions
      type: object
      required:
      - platform
      - timestamp
      title: PaywallViewedRequest
      description: 'Request for tracking paywall viewed event.


        ga4_client_id is optional for native apps (desktop, iOS, Android) - the backend

        will derive it from user_id for cross-device attribution. Web clients should

        provide ga4_client_id from gtag.js cookies for pre-login tracking.'
    AttributionUserData:
      properties:
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: User's email address
        phone_number:
          anyOf:
          - type: string
            pattern: ^\+[1-9]\d{1,14}$
          - type: 'null'
          title: Phone Number
          description: Phone number in E.164 format (e.g. +14155551234)
        first_name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
          description: User's first name
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
          description: User's last name
        fbp:
          anyOf:
          - type: string
          - type: 'null'
          title: Fbp
          description: Meta _fbp cookie value for browser match quality
        fbc:
          anyOf:
          - type: string
          - type: 'null'
          title: Fbc
          description: Meta _fbc click ID cookie value for ad attribution
      type: object
      title: AttributionUserData
      description: Optional user data for enhanced conversions (Google Ads attribution).
  securitySchemes:
    ApiKeyHeaderPatched:
      type: apiKey
      in: header
      name: Authorization
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key