Wispr AI Voice Actions API

openapi: 3.0.3
info:
  title: Wispr Backend Analytics Voice Actions API
  description: Wispr Backend API
  version: 0.5.2
tags:
- name: Voice Actions
paths:
  /api/v1/voice-actions/realtime/schema:
    get:
      tags:
      - Voice Actions
      summary: Voice Actions Realtime Schema
      operationId: voice_actions_realtime_schema
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceActionsServerFrameEnvelope'
  /api/v1/voice-actions/realtime/client-schema:
    get:
      tags:
      - Voice Actions
      summary: Voice Actions Realtime Client Schema
      operationId: voice_actions_realtime_client_schema
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceActionsClientFrameEnvelope'
components:
  schemas:
    VoiceActionsSessionUpdate:
      properties:
        type:
          type: string
          const: session.update
          title: Type
        context:
          type: object
          title: Context
      type: object
      required:
      - type
      title: VoiceActionsSessionUpdate
      description: Refresh the desktop context mid-session (app/textbox/AX context lands after session.start).
    VoiceActionsAudioCommit:
      properties:
        type:
          type: string
          const: audio.commit
          title: Type
      type: object
      required:
      - type
      title: VoiceActionsAudioCommit
      description: Client frame committing the buffered audio and requesting a model response.
    VoiceActionsSessionStart:
      properties:
        type:
          type: string
          const: session.start
          title: Type
        instructions:
          type: string
          maxLength: 20000
          title: Instructions
          default: ''
        tools:
          items:
            $ref: '#/components/schemas/VoiceActionToolDefinition'
          type: array
          maxItems: 64
          title: Tools
        context:
          type: object
          title: Context
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
      type: object
      required:
      - type
      title: VoiceActionsSessionStart
      description: Client frame that opens a voice-actions session with instructions, tools, and context.
    VoiceActionToolDefinition:
      properties:
        name:
          type: string
          maxLength: 128
          title: Name
        description:
          type: string
          maxLength: 4096
          title: Description
          default: ''
        parameters:
          type: object
          title: Parameters
      type: object
      required:
      - name
      title: VoiceActionToolDefinition
      description: A tool the client exposes to the model for this voice-actions session.
    VoiceActionsSessionClose:
      properties:
        type:
          type: string
          const: session.close
          title: Type
      type: object
      required:
      - type
      title: VoiceActionsSessionClose
      description: Client frame that closes the voice-actions session.
    VoiceActionsTranscriptFinal:
      properties:
        type:
          type: string
          const: transcript.final
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
      - type
      - text
      title: VoiceActionsTranscriptFinal
      description: Server frame carrying the finalized input transcript.
    VoiceActionsTextDelta:
      properties:
        type:
          type: string
          const: text.delta
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
      - type
      - text
      title: VoiceActionsTextDelta
      description: Server frame carrying an incremental chunk of the model's text response.
    VoiceActionsTextFinal:
      properties:
        type:
          type: string
          const: text.final
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
      - type
      - text
      title: VoiceActionsTextFinal
      description: Server frame carrying the finalized model text response.
    VoiceActionsSessionReady:
      properties:
        type:
          type: string
          const: session.ready
          title: Type
        provider:
          type: string
          const: openai
          title: Provider
          default: openai
        model:
          type: string
          title: Model
      type: object
      required:
      - type
      - model
      title: VoiceActionsSessionReady
      description: Server frame confirming the session is open, naming the provider and model.
    VoiceActionsTranscriptDelta:
      properties:
        type:
          type: string
          const: transcript.delta
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
      - type
      - text
      title: VoiceActionsTranscriptDelta
      description: Server frame carrying an incremental chunk of the input transcript.
    VoiceActionsToolCall:
      properties:
        type:
          type: string
          const: tool.call
          title: Type
        call_id:
          type: string
          title: Call Id
        name:
          type: string
          title: Name
        arguments:
          type: object
          title: Arguments
      type: object
      required:
      - type
      - call_id
      - name
      - arguments
      title: VoiceActionsToolCall
      description: Server frame requesting the client invoke a tool with the given arguments.
    VoiceActionsError:
      properties:
        type:
          type: string
          const: error
          title: Type
        message:
          type: string
          title: Message
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      type: object
      required:
      - type
      - message
      title: VoiceActionsError
      description: Server frame reporting an error during the session.
    VoiceActionsClientFrameEnvelope:
      properties:
        voice_action_frame:
          oneOf:
          - $ref: '#/components/schemas/VoiceActionsSessionStart'
          - $ref: '#/components/schemas/VoiceActionsSessionUpdate'
          - $ref: '#/components/schemas/VoiceActionsAudioAppend'
          - $ref: '#/components/schemas/VoiceActionsAudioCommit'
          - $ref: '#/components/schemas/VoiceActionsTextInput'
          - $ref: '#/components/schemas/VoiceActionsToolResult'
          - $ref: '#/components/schemas/VoiceActionsPing'
          - $ref: '#/components/schemas/VoiceActionsSessionClose'
          title: Voice Action Frame
          discriminator:
            propertyName: type
            mapping:
              audio.append: '#/components/schemas/VoiceActionsAudioAppend'
              audio.commit: '#/components/schemas/VoiceActionsAudioCommit'
              ping: '#/components/schemas/VoiceActionsPing'
              session.close: '#/components/schemas/VoiceActionsSessionClose'
              session.start: '#/components/schemas/VoiceActionsSessionStart'
              session.update: '#/components/schemas/VoiceActionsSessionUpdate'
              text.input: '#/components/schemas/VoiceActionsTextInput'
              tool.result: '#/components/schemas/VoiceActionsToolResult'
      type: object
      required:
      - voice_action_frame
      title: VoiceActionsClientFrameEnvelope
      description: Envelope wrapping a single discriminated client frame.
    VoiceActionsPing:
      properties:
        type:
          type: string
          const: ping
          title: Type
        ts:
          anyOf:
          - type: string
          - type: 'null'
          title: Ts
      type: object
      required:
      - type
      title: VoiceActionsPing
      description: Client keepalive frame; the server answers with a pong.
    VoiceActionsDone:
      properties:
        type:
          type: string
          const: done
          title: Type
      type: object
      required:
      - type
      title: VoiceActionsDone
      description: Server frame signaling the model response turn is complete.
    VoiceActionsServerFrameEnvelope:
      properties:
        voice_action_event:
          oneOf:
          - $ref: '#/components/schemas/VoiceActionsSessionReady'
          - $ref: '#/components/schemas/VoiceActionsTranscriptDelta'
          - $ref: '#/components/schemas/VoiceActionsTranscriptFinal'
          - $ref: '#/components/schemas/VoiceActionsToolCall'
          - $ref: '#/components/schemas/VoiceActionsTextDelta'
          - $ref: '#/components/schemas/VoiceActionsTextFinal'
          - $ref: '#/components/schemas/VoiceActionsDone'
          - $ref: '#/components/schemas/VoiceActionsPong'
          - $ref: '#/components/schemas/VoiceActionsError'
          title: Voice Action Event
          discriminator:
            propertyName: type
            mapping:
              done: '#/components/schemas/VoiceActionsDone'
              error: '#/components/schemas/VoiceActionsError'
              pong: '#/components/schemas/VoiceActionsPong'
              session.ready: '#/components/schemas/VoiceActionsSessionReady'
              text.delta: '#/components/schemas/VoiceActionsTextDelta'
              text.final: '#/components/schemas/VoiceActionsTextFinal'
              tool.call: '#/components/schemas/VoiceActionsToolCall'
              transcript.delta: '#/components/schemas/VoiceActionsTranscriptDelta'
              transcript.final: '#/components/schemas/VoiceActionsTranscriptFinal'
      type: object
      required:
      - voice_action_event
      title: VoiceActionsServerFrameEnvelope
      description: Envelope wrapping a single discriminated server frame.
    VoiceActionsTextInput:
      properties:
        type:
          type: string
          const: text.input
          title: Type
        text:
          type: string
          maxLength: 60000
          title: Text
      type: object
      required:
      - type
      - text
      title: VoiceActionsTextInput
      description: Final transcript from the client's own ASR pipeline; triggers a model response.
    VoiceActionsAudioAppend:
      properties:
        type:
          type: string
          const: audio.append
          title: Type
        audio:
          type: string
          maxLength: 1000000
          title: Audio
        encoding:
          type: string
          const: pcm16
          title: Encoding
          default: pcm16
        sample_rate:
          type: integer
          const: 24000
          title: Sample Rate
          default: 24000
        channels:
          type: integer
          const: 1
          title: Channels
          default: 1
        position:
          anyOf:
          - type: integer
          - type: 'null'
          title: Position
      type: object
      required:
      - type
      - audio
      title: VoiceActionsAudioAppend
      description: Client frame appending a chunk of PCM16 audio to the session's input buffer.
    VoiceActionsPong:
      properties:
        type:
          type: string
          const: pong
          title: Type
        ts:
          anyOf:
          - type: string
          - type: 'null'
          title: Ts
      type: object
      required:
      - type
      title: VoiceActionsPong
      description: Server keepalive frame answering a client ping.
    VoiceActionsToolResult:
      properties:
        type:
          type: string
          const: tool.result
          title: Type
        call_id:
          type: string
          title: Call Id
        output:
          title: Output
      type: object
      required:
      - type
      - call_id
      - output
      title: VoiceActionsToolResult
      description: Client frame returning the result of a tool call the model requested.
  securitySchemes:
    ApiKeyHeaderPatched:
      type: apiKey
      in: header
      name: Authorization
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key