Create Realtime Transcription
Create a realtime transcription session and get the WebSocket URL and stream token to stream audio.
The Realtime Transcription API is available to Enterprise plan customers on request. Tiro must enable it for the workspace first.
- Call this from your server. Pass
wsUrlandstreamTokento the client that streams audio, and keep the API key on the server - Connect to
wsUrlwith theAuthorization: Bearer <streamToken>header, then send 16 kHz mono PCM s16le audio as binary frames streamTokenappears only in this response. Reuse it to reconnect while the session isOPEN- Requires a workspace API key, or an account API key bound to the workspace whose owner is a workspace member
- Each workspace can have 10
OPENsessions at once - Tiro does not create notes and does not keep the audio. Results arrive only over the WebSocket
Documentation: Quickstart, WebSocket protocol
Authorizations
API key in format {id}.{secret}.
The notes an endpoint returns depend on the key type. A user key reaches the notes that user can see in the app, including notes in their own private folders. A system key (workspace or organization, no user identity) reaches only notes that sit in a folder shared with all workspace members. Notes in a private folder, in a folder shared with only some members, or in no folder at all fall outside a system key's read scope, and scopes do not widen that boundary.
List and search endpoints drop out-of-scope notes from the response without an
error. Single-note reads and their sub-resources return 404, the same response
as a deleted note. See What notes a system key reads.
Body
Optional. Defaults to the key's workspace. If set, it must equal the key's workspace GUID, otherwise the request fails with 403 workspace_access_denied.
"Wk8sQ2mLx1aB7"
Language to transcribe. Omit it, send null, or send AUTO to detect the spoken language.
Accepts ko_KR, ko-KR, and ko, case-insensitive. A language-only tag resolves to its supported region. Regions outside the supported locales, such as en-GB, return 400 unsupported_language.
"ko_KR"
One language to translate into. Omit it or send null for no translation.
Uses the same format as transcriptionLocale. AUTO, or the same language as transcriptionLocale, returns 400 invalid_request.
"en_US"
Response
Session created. The response includes streamToken.
A realtime transcription session. Results are delivered only over the WebSocket at wsUrl, not through this resource.
See WebSocket protocol.
Session ID.
"Rt7Yq2PbX9cDk"
Workspace the session belongs to. Concurrent sessions are counted per workspace.
"Wk8sQ2mLx1aB7"
OPEN: Tiro accepts audio. You can connect and reconnect. The session holds a concurrent slotENDED: The session is over. You cannot reconnect
New values can appear. Treat an unknown value as not ENDED.
OPEN, ENDED "OPEN"
WebSocket URL to connect to. Use it as returned. Do not build or hard-code the host or path.
"wss://api.tiro.ooo/v1/external/realtime-transcriptions/Rt7Yq2PbX9cDk/stream"
Maximum session length, counted from the first connection. Currently 10,800,000 (3 hours).
10800000
Audio length Tiro has received so far, including connections that already closed.
0
When the session was created.
"2026-11-05T09:00:00Z"
Public ID of the API key that created the session, matching apiKeyId from GET /v1/external/auth/me. null only when Tiro can no longer find that key.
"tk_8f2a91c0d3e4"
Why the session ended. null while OPEN.
CLIENT_REQUESTED: WebSocketsession.endor End Realtime TranscriptionIDLE_TIMEOUT: No audio for 15 minutesMAX_DURATION: 3 hours since the first connectionINTERNAL_ERROR: Tiro could not continue the session
New values can appear. Treat an unknown value as a normal end.
CLIENT_REQUESTED, IDLE_TIMEOUT, MAX_DURATION, INTERNAL_ERROR null
Token for the WebSocket Authorization: Bearer header. Present only in the Create Realtime Transcription response.
Opaque, up to 512 characters. Valid for this session while it is OPEN.
"rtt_5Hq3..."
Transcription locale applied to the session. null means auto detection.
"ko_KR"
Translation locale. null means no translation.
"en_US"
When the session ended. null while OPEN.
null