> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.wisprflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST with Client auth

> Convert speech to text using client-side authentication

Convert audio to text with client-side JWT authentication. This endpoint is identical to the standard `/api` endpoint but uses a client token (JWT) instead of an org-level API key.

### Request Body

<ParamField body="audio" type="string" required>
  Base64 encoded, 16kHz wav audio. Maximum size is 25MB or 6 minutes of audio.
</ParamField>

<ParamField body="language" type="array">
  Optional list of (ISO 639-1) language codes that the user is expected to speak.

  Setting the list size to 1 forces the transcription into the specified language. Not providing an input attempts autodetection on full list of languages (less accurate).
</ParamField>

<ParamField body="context" type="object">
  Optional contextual information about the circumstances surrounding the user dictation.

  Flow can use these information to make its output more accurate by for example, getting names right, resolving speech ambiguities, etc.

  All properties are optional and will use default values if not provided.

  <Expandable>
    <ParamField body="app" type="object">
      Information about the application the user is dictating into, used to customize the writing style.

      <Expandable>
        <ParamField body="name" type="string">
          The name of the application.
        </ParamField>

        <ParamField body="type" type="string">
          The type of the application. Currently supports the following list:

          * `email`: Email clients and anywhere the user would be trying to dictate an email.
          * `ai`: Applications where the user is conversing with an AI chatbot / agent and not a human.
          * `other`: Any application that does not fit in the two groups above.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="dictionary_context" default="[]" type="array">
      List of uncommon names or words relevant to the context that might be mentioned by the user.
    </ParamField>

    <ParamField body="user_identifier" type="string">
      User ID in the app that the person is dictating in, like their email address in an email client application.
    </ParamField>

    <ParamField body="user_first_name" type="string">
      First name of the speaker, used to make sure Flow spells the speaker's name correctly.
    </ParamField>

    <ParamField body="user_last_name" type="string">
      Last name of the speaker.
    </ParamField>

    <ParamField body="textbox_contents" type="object">
      Text under and surrounding the cursor in the active textbox. Flow uses this information to decide casing, spacing and punctuation.

      <Expandable>
        <ParamField body="before_text" type="object">
          The text immediately before the cursor.
        </ParamField>

        <ParamField body="selected_text" type="object">
          The text the user has highlighted.
        </ParamField>

        <ParamField body="after_text" type="object">
          The text immediately after the cursor.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="screenshot" type="string">
      Screenshot of the screen or the app the user is dictating in, for when the user is referencing something on the screen.
    </ParamField>

    <ParamField body="content_text" type="string">
      Plaintext content of the current page in the app user is dictating in. This is a more efficient way of providing context compared to screenshot.
    </ParamField>

    <ParamField body="content_html" type="string">
      HTML content of the app user is dictating in (a more feature-rich alternative to `content_text`).
    </ParamField>

    <ParamField body="conversation" type="object">
      Chatbot style history of the conversation the user is dictating in. This typically applies to messaging and AI apps.

      <Expandable>
        <ParamField body="id" type="string" required>
          Identifier of the conversation. For example name of group chat in case of a messaging app.
        </ParamField>

        <ParamField body="participants" type="array">
          List of names of other people in the conversation, used to get their names correct in case of uncommonly spelled names.
        </ParamField>

        <ParamField body="messages" type="array">
          List of recent messages in the conversation, in the chronological order. Used to identify proper context and names of things being mentioned that are not conversation participants.

          <Expandable title="message item attributes">
            <ParamField body="role" type="string" required>
              Type of the message sender. One of: `user`, `human`, `assistant`
            </ParamField>

            <ParamField body="content" type="string" required>
              Content of the message.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="properties" type="object" deprecated>
  <Expandable title="properties">
    <ParamField body="language" default="en" type="string">
      2-digit ISO language code (e.g. 'en', 'es')
    </ParamField>

    <ParamField body="app_type" default="other" type="string">
      Flow formats appropriately depending on if the user is prompting AI, writing an email, or other tasks.
      Options: 'ai', 'email', 'other'
    </ParamField>

    <ParamField body="dictionary" default="[]" type="array">
      List of dictionary words to help with transcription accuracy
    </ParamField>

    <ParamField body="after_text" default type="string">
      The text immediately after the cursor. Flow uses it to decide spacing / punctuation.
    </ParamField>

    <ParamField body="before_text" default type="string">
      The text immediately before the cursor. Flow uses it to decide spacing / punctuation.
    </ParamField>

    <ParamField body="selected_text" default type="string">
      The text the user has highlighted. Flow uses it to decide spacing / punctuation.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseExample>
  ```json Response (200 OK) theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Testing testing 1, 2, 3",
    "detected_language": "en",
    "total_time": 432,
    "generated_tokens": 9
  }
  ```
</ResponseExample>

<RequestExample>
  ```json Request theme={null}
  {
    "audio": "UklGRiQA....",
    "language": ["en"],
    "context": {
      "app": {
        "type": "email"
      },
      "dictionary_context": [],
      "textbox_contents": {
        "before_text": "",
        "selected_text": "",
        "after_text": ""
      },
      // ... for a full list of available fields, see the "Request Schema" page
    }
  }
  ```
</RequestExample>


## OpenAPI

````yaml POST /client_api
openapi: 3.1.0
info:
  title: Client-Side Authentication & API
  version: 1.0.0
  description: |
    Endpoints for managing and using client-side tokens (JWT). 
    Generate or revoke tokens with your org-level API key, 
    then call the client-specific endpoints using the JWT.
servers:
  - url: https://platform-api.wisprflow.ai/api/v1/dash
    description: Production server
security: []
paths:
  /client_api:
    post:
      summary: Client-side speech-to-text (JWT-based)
      description: |
        Identical to the standard `/api` endpoint, but uses a client token (JWT)
        in the Authorization header instead of an org-level API key.
      operationId: clientApiTranscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - audio
                - properties
              properties:
                audio:
                  type: string
                  description: Base64-encoded audio data (up to 25MB / 6 minutes)
                properties:
                  type: object
                  description: Additional config for transcription
      responses:
        '200':
          description: Successful transcription
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  text:
                    type: string
                  detected_language:
                    type: string
                  total_time:
                    type: number
                  generated_tokens:
                    type: integer
        '400':
          description: Bad request
        '401':
          description: Unauthorized (invalid or expired client JWT)
        '413':
          description: Payload too large
        '500':
          description: Internal server error
      security:
        - jwtAuth: []
components:
  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        **Client-side token** (format: `Bearer <JWT>`)  for calling client
        endpoints like `/client_api`.

````