Wispr AI keyboard_telemetry API

openapi: 3.0.3
info:
  title: Wispr Backend Analytics keyboard_telemetry API
  description: Wispr Backend API
  version: 0.5.2
tags:
- name: keyboard_telemetry
paths:
  /api/v1/keyboard_telemetry/ingest:
    post:
      tags:
      - keyboard_telemetry
      summary: Ingest keyboard touch aggregate cells (staging-gated)
      operationId: ingest_keyboard_telemetry
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KbTouchBatch'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KbTouchIngestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyHeaderPatched: []
components:
  schemas:
    KbTouchIngestResponse:
      properties:
        accepted:
          type: integer
          title: Accepted
      type: object
      required:
      - accepted
      title: KbTouchIngestResponse
      description: Response reporting how many touch cells were accepted for ingestion.
    KbTouchCell:
      properties:
        device_diag:
          type: string
          maxLength: 16
          minLength: 1
          title: Device Diag
        device_model:
          type: string
          maxLength: 64
          minLength: 1
          title: Device Model
        os_major:
          type: string
          maxLength: 32
          minLength: 1
          title: Os Major
        app_version:
          type: string
          maxLength: 32
          minLength: 1
          title: App Version
        layout_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Layout Id
        orientation:
          type: string
          maxLength: 16
          minLength: 1
          title: Orientation
        key_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Key Id
        sub_cell:
          type: integer
          maximum: 8.0
          minimum: 0.0
          title: Sub Cell
        intended_key:
          type: string
          maxLength: 128
          minLength: 1
          title: Intended Key
        label_source:
          type: string
          maxLength: 64
          minLength: 1
          title: Label Source
        n:
          type: integer
          maximum: 2000.0
          minimum: 1.0
          title: N
        sum_dx:
          type: number
          title: Sum Dx
        sum_dy:
          type: number
          title: Sum Dy
        sum_dx2:
          type: number
          minimum: 0.0
          title: Sum Dx2
        sum_dy2:
          type: number
          minimum: 0.0
          title: Sum Dy2
        sum_dxdy:
          type: number
          title: Sum Dxdy
        sum_t:
          type: number
          minimum: 0.0
          title: Sum T
        sum_t2:
          type: number
          minimum: 0.0
          title: Sum T2
      type: object
      required:
      - device_diag
      - device_model
      - os_major
      - app_version
      - layout_id
      - orientation
      - key_id
      - sub_cell
      - intended_key
      - label_source
      - n
      - sum_dx
      - sum_dy
      - sum_dx2
      - sum_dy2
      - sum_dxdy
      - sum_t
      - sum_t2
      title: KbTouchCell
      description: A single per-key moment-counter cell aggregated on-device.
    KbTouchBatch:
      properties:
        batch_id:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          title: Batch Id
        cells:
          items:
            $ref: '#/components/schemas/KbTouchCell'
          type: array
          maxItems: 500
          minItems: 1
          title: Cells
      type: object
      required:
      - batch_id
      - cells
      title: KbTouchBatch
      description: A batch of keyboard touch aggregate cells uploaded by the client.
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    ApiKeyHeaderPatched:
      type: apiKey
      in: header
      name: Authorization
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key