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

# Create Dictation Session

> Create a Dictation session to transcribe spoken audio into text in real time

Use this endpoint to create a Dictation (The process of speaking aloud to create written text, often used by clinicians to create medical documentation using voice input.) session to transcribe spoken audio into text.
Refer to the [Audio Dictation guide](https://developer.suki.ai/documentation/concepts/dictation/dictation.md) for more information.

> [!NOTE]
>
> `audio_config.audio_language` supports **`English`** and **`Multilingual`**. If you omit `audio_config`, language defaults to **`English`**. Refer to [Dictation basic usage](https://developer.suki.ai/documentation/how-to/dictation/dictation-basic-usage.md) guide for more information.

Returns a `201 Created` status with the `transcription_session_id` that is used to identify the session for transcribing audio and ending the session.


## OpenAPI

````yaml POST /api/v1/transcription/session/create
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, content rewrite, and
    reference metadata endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/transcription/session/create:
    post:
      tags:
        - /api/v1/transcription/session
      summary: Create transcription session
      description: >-
        Creates a transcription session for real-time speech-to-text over
        WebSocket. Returns a `transcription_session_id` to use when connecting
        to `/ws/transcribe`.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/controllers.CreateTranscriptionSessionRequest
        required: false
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/controllers.CreateTranscriptionSessionResponse
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '403':
          description: Forbidden. The authenticated user cannot access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ForbiddenError'
        '404':
          description: Not found. The session, encounter, or resource ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST \
              --url https://sdp.suki.ai/api/v1/transcription/session/create \
              --header 'Content-Type: application/json' \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** for standard partners.


        **Required** for:


        - **Bearer authentication.** Use the same `provider_id` returned by the
        Login or Register API.

        - **Single Auth Token authentication.** Include the same `provider_id`
        on every request as `sdp_provider_id`.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.CreateTranscriptionSessionRequest:
      type: object
      properties:
        audio_config:
          type: object
          description: '**Optional** - Audio configuration for the transcription session'
          allOf:
            - $ref: '#/components/schemas/controllers.TranscriptionAudioConfig'
        transcription_session_id:
          type: string
          description: >-
            **Optional** - UUID format. If not provided, a session ID will be
            automatically generated.
          example: 123dfg-456dfg-789dfg-012dfg
      description: >-
        Optional transcription session ID and audio configuration. Suki
        generates an ID when omitted.
      example:
        audio_config:
          audio_encoding: LINEAR16
          audio_language: en-US
          sample_rate_hertz: 16000
        transcription_session_id: 123dfg-456dfg-789dfg-012dfg
    controllers.CreateTranscriptionSessionResponse:
      type: object
      properties:
        transcription_session_id:
          type: string
          description: Unique identifier for the transcription session
          example: 123dfg-456dfg-789dfg-012dfg
      description: Response body for the /transcription/session/create endpoint
      example:
        transcription_session_id: 123dfg-456dfg-789dfg-012dfg
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.ForbiddenError:
      type: object
      properties:
        code:
          type: integer
          example: 403
          description: HTTP status code for the error.
        message:
          type: string
          example: forbidden
          description: Human-readable description of the authorization failure.
      description: Error response when the caller lacks permission.
    controllers.NotFoundError:
      description: Not Found Response
      type: object
      properties:
        code:
          type: integer
          example: 404
        message:
          type: string
          example: not found
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.TranscriptionAudioConfig:
      type: object
      properties:
        audio_encoding:
          type: string
          description: '**Optional** - Audio encoding format'
          example: LINEAR16
          enum:
            - LINEAR16
        audio_language:
          type: string
          description: '**Optional** - Language code for audio transcription'
          example: en-US
        sample_rate_hertz:
          type: integer
          description: '**Optional** - Sample rate in Hertz'
          example: 16000
      description: Audio configuration for transcription
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.