> ## 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
> Creates a transcription session for real-time speech-to-text over WebSocket. Returns a `transcription_session_id` to use when connecting to `/ws/transcribe`.
Use this endpoint to create a dictation session to transcribe audio from patient-provider conversations into text.
Refer to the [Audio dictation guide](/documentation/dictation) 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, 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: ' \
--header 'sdp_provider_id: '
components:
parameters:
ProviderIdHeader:
name: sdp_provider_id
in: header
description: >-
**Optional** - Stable identifier for the active provider. Omit for
standard partners whose `partner_token` identifies the user.
**Required** for Bearer partners and Single Auth Token authentication
where multiple providers share one `partner_token`. Use the same
`provider_id` you sent on Login or Register.
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:
type: object
properties:
code:
type: integer
example: 400
description: HTTP status code for the error.
message:
type: string
example: invalid request
description: Human-readable description of the validation or request error.
description: Error response when the request fails validation.
controllers.AuthenticationError:
type: object
properties:
code:
type: integer
example: 401
description: HTTP status code for the error.
message:
type: string
example: invalid token
description: Human-readable description of the authentication failure.
description: Error response when authentication fails.
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:
type: object
properties:
code:
type: integer
example: 404
description: HTTP status code for the error.
message:
type: string
example: not found
description: Human-readable description of the missing resource.
description: Error response when the requested resource was not found.
controllers.InternalServerError:
type: object
properties:
code:
type: integer
example: 500
description: HTTP status code for the error.
message:
type: string
example: internal server error
description: Human-readable description of the server error.
description: Error response when the server encounters an unexpected 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 for the authenticated provider. Obtain this by calling
Login or Register with a valid `partner_token`. Pass the `suki_token`
value from the JSON response as the `sdp_suki_token` header on REST
requests and non-browser WebSocket upgrades. Browser WebSocket clients
pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
one hour; call Login again to refresh.
````