Real-time stateless dictation

Overview

The WebSocket Secure (WSS) /transcribe API enables real-time, bidirectional communication with the Corti system for stateless speech to text. Clients can send and receive structured data, including transcripts and detected commands. This documentation provides a comprehensive guide for integrating these capabilities.

This /transcribe endpoint supports real-time stateless dictation.

If you are looking for real-time ambient documentation interactions, you should use the /stream WSS
If you are looking for transcript generation based on a pre-recorded audio file, then please refer to the /transcripts endpoint

1. Establishing a Connection

Clients must initiate a WebSocket connection using the wss:// scheme.

The authentication for the WSS stream requires in addition to the tenant-name parameter a token parameter to pass in the Bearer access token.

Query Parameters

environment

enum

required

eu or us

tenant-name

string

required

Specifies the tenant context

token

string

required

Bearer $token

Example wss:/transcribe request

  curl --request GET \
    --url wss://api.${environment}.corti.app/audio-bridge/v2/transcribe?tenant-name=${tenant}&token=Bearer%20${accessToken}

Using SDK

You can use the Corti SDK (currently in “beta”) to connect to the /transcribe endpoint.

import { CortiClient, CortiEnvironment } from "@corti/sdk";

const cortiClient = new CortiClient({
    tenantName: "YOUR_TENANT_NAME",
    environment: CortiEnvironment.Eu,
    auth: {
        accessToken: "YOUR_ACCESS_TOKEN"
    },
});

const transcribeSocket = await cortiClient.transcribe.connect();

2. Handshake Response

101 Switching Protocols

Indicates a successful WebSocket connection. Upon successful connection, send a config message to define the configuration: Specify the input language and expected output preferences.

The config message must be sent within 10 seconds of the web socket being opened to prevent CONFIG-TIMEOUT, which will require establishing a new wss connection.

3. Sending Messages

Configuration

Declare your /transcribe configuration using the message "type": "config" followed by defining the "configuration": {<config details, per options below>}. Defining the type is required along with the primaryLanguage configuration parameter. The other parameters are optional for use, depending on your need and workflow.

Configuration notes:

Clients must send a stream configuration message and wait for a response of type CONFIG_ACCEPTED before transmitting other data.
If the configuration is not valid it will return CONFIG_DENIED.
The configuration must be committed within 10 seconds of opening the WebSocket, else it will time-out with CONFIG_TIMEOUT.

type

string

default:"config"

required

configuration

object

required

Hide child attributes

primaryLanguage

string

required

The locale of the primary spoken language. See supported languages codes and more information here.

spokenPunctuation

bool

When true, converts spoken punctuation such as period or slash into .or /. Read more about supported punctuation here.

automaticPunctuation

bool

When true, automatically punctuates and capitalizes in the final transcript.

Spoken and Automatic Punctuation are mutually exclusive - only one should be set to true in a given configuration request. If both are included and set to true, then spokenPunctuation will take precedence and override automaticPunctuation.

commands

object

Provide the commands that should be registered and detected - Read more about commands here.

Show child attributes

string

required

Unique value to identify the command. This, along with the command phrase, will be returned by the API when the command is recognized during dictation.

phrases

string[]

required

One or more word sequence(s) that can be spoken to trigger the command. At least one phrase is required per command.

variables

string[]

Placeholders that can (optionally) be added in phrases to define multiple words that should trigger the command.

Show child attributes

key

string

required

Define the variable used in command phrase here.

type

enum

required

The only variable type supported at this time is enum.

enum

string[]

required

List of values that should be recognized for the defined variable.

formatting

object

Define each type of formatting preferences using the enum options described below. Formatting configuration is optional, and when no properties are configured, the values listed as default will be applied automatically. Read more about formatting here.

Formatting is currently in beta testing. API details subject to change ahead of general release.

Show child attributes

dates

enum

Option	Format	Example
`as_dictated`	Preserve spoken phrasing	”February third twenty twenty five” -> “February 3rd 2025”
`long_text`	Long date	”3 February 2025”
`eu_slash`	Short date (EU)	“03/02/2025”
`us_slash`	Short date (US)	“02/03/2025”
`iso_compact`	ISO (basic, no separators)	“20250302”

times

enum

Option	Format	Example
`as_dictated`	As dictated	”Four o’clock” or “four thirty five” or “sixteen hundred”
`h12`	12-hour	”4:00 PM”
`h24`	24-hour	”16:00”

numbers

enum

Option	Format	Example
`as_dictated`	As dictated	”one, two, … nine, ten, eleven, twelve
`numerals_above_nine`	Single digit as words, multi-digit as number	”One, two … nine, 10, 11, 12”
`numerals`	Numbers only	”1, 2, … 9, 10, 11, 12”

measurements

enum

Option	Format	Example	Default
`as_dictated`	As dictated	”Millimeters, centimeters, inches; Blood pressure one twenty over eighty”
`abbreviated`	Abbreviated	”mm, cm, in; BP 120/80”

Click here to see a full list of supported units and measurements

numericRanges

enum

Option	Format	Example	Default
`as_dictated`	As dictated	”one to ten”
`numerals`	As numbers	”1-10”

ordinals

enum

Option	Format	Example	Default
`as_dictated`	As dictated	”First, second, third”
`numerals`	Abbreviated	”1st, 2nd, 3rd”

Example

Here is an example configuration for transcription of dictated audio in English with spoken punctuation enabled, two commands defined, and (default) formatting options defined:

wss:/transcribe configuration example

{
  "type": "config",
  "configuration":{
    "primaryLanguage": "en",
    "spokenPunctuation": true, 
    "commands": [
      {
        "id": "next_section",
        "phrases": [
          "next section", "go to next section"
        ]
      },
      {
        "id": "insert_template",
        "phrases": [
          "insert my {template_name} template", "insert {template_name} template"
        ],
        "variables": [
          {
            "key": "template_name",
            "type": "enum",
            "enum": [
              "soap", "radiology", "referral"
            ]
          }
        ]
      }
    ],
    "formatting": {
      "dates": "long_text",
      "times": "h24",
      "numbers": "numerals_above_nine",
      "measurements": "abbreviated",
      "numericRanges": "numerals",
      "ordinals": "numerals"
    }
  }
}

Using SDK

You can use the Corti SDK (currently in “beta”) to send configuration.

You can provide the configuration either directly when connecting, or send it as a separate message after establishing the connection:

const configuration = {
    primaryLanguage: "en",
    spokenPunctuation: true,
    commands: [
      {
        id: "next_section",
        phrases: ["next section", "go to next section"]
      },
    ]
  };

const transcribeSocket = await cortiClient.transcribe.connect(
  { configuration }
);

Sending Audio

Ensure that your configuration was accepted before sending audio, and that the initial audio chunk is not too small as it needs to contain the headers to properly decode the audio.We recommend sending audio in chunks of 250-500ms. In terms of buffering, the limit is 64000 bytes per chunk.Audio data should be sent as raw binary without JSON wrapping.

A variety of common audio formats are supported; audio will be passed through a transcoder before speech-to-text processing. Similarly, specification of sample rate, depth or other audio settings is not required at this time. See more details on supported audio formats here.

Using SDK

You can use the Corti SDK (currently in “beta”) to send audio data.

transcribeSocket.sendAudio(audioChunk); // method doesn't do the chunking

Flush the Audio Buffer

To flush the audio buffer, forcing transcript segments and detected commands to be returned over the web socket (e.g., when turning off or muting the microphone in a “hold-to-talk” dictation workflow, or in applications that support mic “go to sleep”), send a message -

{
  "type":"flush"
}

The server will return text/commands for audio sent before the flush message and then respond with message -

{
  "type":"flushed"
}

The web socket will remain open so dictation can continue.

Client side considerations:¹ If you rely on a flush event to separate data (e.g., for different sections in an EHR template), then be sure to receive the flushed event before moving on to the next data field.² When using a web browser MediaRecorder API, audio is buffered and only emitted at the configured timeslice interval. Therefore, before sending a flush message, call MediaRecorder.requestData() to force any remaining buffered audio on the client to be transmitted to the server. This ensures all audio reaches the server before the flush is processed.

Ending the Session

To end the /transcribe session, send a message -

{
"type": "end"
}

This will signal the server to send any remaining transcript segments and/or detected commands. Then, the server will send two messages -

{
  "type":"usage",
  "credits":0.1
}

{
  "type":"ended"
}

Following the message type ended, the server will close the web socket.

Using SDK

You can use the Corti SDK (currently in “beta”) to end the /transcribe session.

When using automatic configuration (passing configuration to connect), the socket will close itself without reconnecting when it receives an ended message. When using manual configuration, the socket will attempt to reconnect after the server closes the connection. To prevent this, you must subscribe to the ended message and manually close the connection.

const transcribeSocket = await cortiClient.transcribe.connect({
  configuration
});

transcribeSocket.sendEnd({ type: "end" });

4. Responses

Configuration

type

string

default:"CONFIG_ACCEPTED"

required

Returned when sending a valid configuration.

sessionId

uuid

required

Returned when sending a valid configuration.

Transcripts

type

string

default:"transcript"

required

data

string

required

Show child attributes

text

string

required

Transcript segment with punctuations applied and command phrases removed

rawTranscriptText

string

required

The raw transcript without spoken punctuation applied and without command phrases removed

start

float64

required

Start time of the transcript segment in seconds

end

float64

required

End time of the transcript segment in seconds

isFinal

bool

required

If false, then interim transcript result

Transcript response

{
"type": "transcript",
"data": {
    "text": "patient reports mild chest pain.",
    "rawTranscriptText": "patient reports mild chest pain period",
    "start": 0.0,
    "end": 3.2,
    "isFinal": true
}
}

Commands

type

string

default:"command"

required

data

string

required

Show child attributes

string

required

To identify the command when it gets detected and returned over the WebSocket

variables

string[]

The variables identified

rawTranscriptText

string

required

The raw transcript without spoken punctuation applied and without command phrases removed

start

float64

required

Start time of the transcript segment in seconds

end

float64

required

End time of the transcript segment in seconds

Command response

{
  "type": "command",
  "data": {
    "id": "insert_template",
    "variables": {
      "template_name": "radiology"
    },
    "rawTranscriptText": "insert my radiology template",
    "start": 2.3,
    "end": 2.9,
  }
}

Flushed

type

string

default:"flushed"

required

Returned by server, after processing flush event from client, to return transcript segments/ detected commands

{
  "type":"flushed"
}

Ended

type

string

default:"usage"

required

Returned by server, after processing end event from client, to convey amount of credits consumed

{
  "type":"usage",
  "credits":0.1
}

type

string

default:"ended"

required

Returned by server, after processing end event from client, before closing the web socket

{
  "type":"ended"
}

Using SDK

You can use the Corti SDK (currently in “beta”) to subscribe to responses from the /transcribe endpoint.

transcribeSocket.on("message", (message) => {
  switch (message.type) {
    case "transcript":
      console.log("Transcript:", message.data.text);
      break;
    case "command":
      console.log("Command detected:", message.data.id, message.data.variables);
      break;
    case "error":
      console.error("Error:", message.error);
      break;
    case "usage":
      console.log("Usage credits:", message.credits);
      break;
    default:
      // handle other messages
      break;
  }
});

5. Error Responses

type

string

required

Returned when sending an invalid configuration.Possible errors CONFIG_DENIED, CONFIG_TIMEOUT

reason

string

The reason the configuration is invalid.

sessionId

uuid

required

The session ID.

Once configuration has been accepted and the session is running, you may encounter runtime or application-level errors. These are sent as JSON objects with the following structure:

{
  "type": "error",
  "error": {
    "id": "error id",
    "title": "error title",
    "status": 400,
    "details": "error details",
    "doc":"link to documentation"
  }
}

In some cases, receiving an “error” type message will cause the stream to end and send a message of type usage and type ENDED.

Using SDK

You can use the Corti SDK (currently in “beta”) to handle error messages.

With recommended configuration, configuration errors (e.g., CONFIG_DENIED, etc.) and runtime errors will both trigger the error event and automatically close the socket. You can also inspect the original message in the message handler. With manual configuration, configuration errors are only received as messages (not as error events), and you must close the socket manually to avoid reconnection.

const transcribeSocket = await cortiClient.transcribe.connect({
  configuration
});

transcribeSocket.on("error", (error) => {
  // Emitted for both configuration and runtime errors
  console.error("Error event:", error);
  // The socket will close itself automatically
});

// still can be accessed with normal "message" subscription
transcribeSocket.on("message", (message) => {
  if (
    message.type === "CONFIG_DENIED" ||
    message.type === "CONFIG_TIMEOUT"
  ) {
    console.log("Configuration error (message):", message);
  }

  if (message.type === "error") {
    console.log("Runtime error (message):", message);
  }
});

Web Socket APIs

REST APIs

Agentic APIs (beta)

Admin APIs

Overview

1. Establishing a Connection

Query Parameters

Using SDK

2. Handshake Response

101 Switching Protocols

3. Sending Messages

Configuration

Example

Using SDK

Sending Audio

Using SDK

Flush the Audio Buffer

Ending the Session

Using SDK

4. Responses

Configuration

Transcripts

Commands

Flushed

Ended

Using SDK

5. Error Responses

Using SDK

Web Socket APIs

REST APIs

Agentic APIs (beta)

Admin APIs

​Overview

​1. Establishing a Connection

​Query Parameters

​Using SDK

​2. Handshake Response

​101 Switching Protocols

​3. Sending Messages

​Configuration

​Example

​Using SDK

​Sending Audio

​Using SDK

​Flush the Audio Buffer

​Ending the Session

​Using SDK

​4. Responses

​Configuration

​Transcripts

​Commands

​Flushed

​Ended

​Using SDK

​5. Error Responses

​Using SDK

Overview

1. Establishing a Connection

Query Parameters

Using SDK

2. Handshake Response

101 Switching Protocols

3. Sending Messages

Configuration

Example

Using SDK

Sending Audio

Using SDK

Flush the Audio Buffer

Ending the Session

Using SDK

4. Responses

Configuration

Transcripts

Commands

Flushed

Ended

Using SDK

5. Error Responses

Using SDK