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 /streams 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 streams 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

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

// Replace these with your values
const ACCESS_TOKEN = "<your-access-token>";

const client = new CortiClient({
  auth: {
    accessToken: ACCESS_TOKEN,
  },
});

using Corti;

// Replace these with your values
const string ACCESS_TOKEN = "<your-access-token>";

var client = new CortiClient(
    auth: CortiClientAuth.Bearer(accessToken: ACCESS_TOKEN)
);

# Replace these with your values
ACCESS_TOKEN="<your-access-token>"
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"

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

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

var transcribe = await client.CreateTranscribeApiAsync();
await transcribe.ConnectAsync();

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": {...}. 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:

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

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.

interimResults

boolean

When true, interim (preview) transcript results ("isFinal"=false) will be returned with lower latency than final transcript results.

spokenPunctuation

boolean

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

automaticPunctuation

boolean

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

array

Define dictation commands to be registered and detected during audio recording.Read more about commands, with examples, 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

array

Placeholders that can (optionally) be added in phrases to provide flexibility and extensibility for triggering commands.

Show child attributes

key

string

required

Define the variable used in command phrase here.

type

enum

required

Possible values:

enum - use to define a list of values that can be recognized for a given command phrase
wildcard - use for any free text utterance to be recognized in a command phrase

When using wildcard type, the phrase must include a literal trigger word before the variable, and multiple wildcard variables in one phrase must be separated by a non-empty literal string.

enum

string[]

Required when type is "enum". List of values that should be recognized for the defined variable. Not used (and ignored) when type is "wildcard".

formatting

object

Define preferences for output formatting using the enum options described below. Formatting configuration is optional, and one or more fields can be defined individually. When a property is not provided for a given field, then the values listed as default will be applied automatically.Read more about formatting options, including how localization is handled per language, and detailed examples, here.

Show child attributes

dates

enum

Default option: locale:long
Alternative options: locale:medium, locale:short, iso, as_dictated

times

enum

Default option: locale
Alternative options: h24, h12

numbers

enum

Default option: numerals_above_nine
Alternative options: numerals, as_dictated

Localization of numbers applied automatically for thousands and decimal separators

measurements

enum

Default option: abbreviated
Alternative options: as_dictated

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

numericRanges

enum

Default option: numerals
Alternative options: as_dictated

ordinals

enum

Default option: numerals_above_nine
Alternative options: numerals, as_dictated

audioFormat

string

Define the audio format of the incoming audio stream - optional but recommended.

When omitted, the server auto-detects the format from the first audio chunk using ffprobe. Supported audio will be processed. Unsupported return an error but might in some cases error silently.
If provided (recommended), the provided MIME type must be supported and the audio must match the MIME type. An unsupported MIME type results in CONFIG_REJECTED. Audio that differs from the MIME type will return audio validation errors on the socket.

See more about supported formats here.

audioEvents

object

Enables audio quality and speech activity events to be sent over the WebSocket. The following events are supported:

Speech quality issue detected / recovered
Long silence detected / recovered

Show child attributes

enabled

boolean

required

When true, enables audio quality and speech activity events to be sent over the WebSocket. Disabled by default.

replacements

array

Don’t like how Corti STT outputs certain words, phrases, or acronyms? Define replacements to have terms (single words or multi-word phrases) replaced in final text output with your preferred style.

Show child attributes

find

string

required

Speech-to-text output to be replaced (case insensitive)

replace

string

required

Replacement text to be used final transcript

A limit of 1,000 items is enforced on configuration validation.

keyterms

object

Define words, terms, and phrases to be recognized by Corti speech-to-text. Especially useful for proper nouns (e.g., surnames), but also supportive of words not being recognized consistently.

Show child attributes

terms

array

Ordered list of words to be recognized (case sensitive)

Hide child attributes

term

string

required

Word to be recognized, defined in it’s expected “written form”

A defined term is limited to a length of 50 characters

A limit of 1,000 items is enforced on configuration validation

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:

{
  "type": "config",
  "configuration":{
    "primaryLanguage": "en",
    "interimResults": true,
    "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"]
          }
        ]
      },
      {
        "id": "select_text",
        "phrases": ["select {text}"],
        "variables": [
          {
            "key": "text",
            "type": "wildcard"
          }
        ]
      },
    ],
    "formatting": {
      "dates": "locale:long",
      "times": "locale",
      "numbers": "numerals_above_nine",
      "measurements": "abbreviated",
      "numericRanges": "numerals",
      "ordinals": "numerals_above_nine"
    },
    "audioFormat": "audio/ogg",
    "audioEvents":{
      "enabled": true
    },
    "replacements": [
      {
        "find": "BID",
        "replace": "twice daily"
      }
    ],
    "keyterms": {
      "terms": [
        {
          "term": "Corti"
        }
      ]
    }
  }
}

const 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"]
          }
        ]
      },
      {
        id: "select_text",
        phrases: ["select {text}"],
        variables: [
          {
            key: "text",
            type: "wildcard"
          }
        ]
      },
    ],
    audioEvents: {
      enabled: true
    },
    replacements: [
      {
        find: "BID",
        replace: "twice daily"
      }
    ],
    keyterms: {
      terms: [{ term: "Corti" }]
    }
  };

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

var transcribe = await client.CreateTranscribeApiAsync();

await transcribe.ConnectAsync(new TranscribeConfig
{
    PrimaryLanguage = "en",
    SpokenPunctuation = true,
    Commands = new List<TranscribeCommand>
    {
        new()
        {
            Id = "next_section",
            Phrases = new List<string> { "next section", "go to next section" },
        },
        new()
        {
            Id = "insert_template",
            Phrases = new List<string>
            {
                "insert my {template_name} template",
                "insert {template_name} template",
            },
            Variables = new List<TranscribeCommandVariable>
            {
                new()
                {
                    Key = "template_name",
                    Type = TranscribeCommandVariableType.Enum,
                    Enum = new List<string> { "soap", "radiology", "referral" },
                },
            },
        },
        new()
        {
            Id = "select_text",
            Phrases = new List<string> { "select {text}" },
            Variables = new List<TranscribeCommandVariable>
            {
                new()
                {
                    Key = "text",
                    Type = TranscribeCommandVariableType.Wildcard,
                },
            },
        },
    },
    AudioEvents = new TranscribeAudioEventsConfig { Enabled = true },
    Replacements = new List<TranscribeConfigReplacementsItem>
    {
        new() { Find = "BID", Replace = "twice daily" },
    },
    Keyterms = new TranscribeConfigKeyterms
    {
        Terms = new List<TranscribeConfigKeytermsTermsItem>
        {
            new() { Term = "Corti" },
        },
    },
});

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.

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

await transcribe.Send(audioChunkBytes); // 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"
}

transcribeSocket.sendFlush({ type: "flush" });

await transcribe.Send(new TranscribeFlushMessage());

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

{
  "type": "flushed"
}

{
  "type": "delta_usage",
  "credits": 0.00116
}

Delta usage represents incremental credit consumption between recording initiation and flush events. Delta usage is approximate and may differ slightly from final usage sent after end message is processed (see below). Final, end session usage will be reflected in API billing. The web socket will remain open after flush processing 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"
}

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

await transcribe.Send(new TranscribeEndMessage());

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.

4. Responses

Configuration

type

string

default:"CONFIG_ACCEPTED"

required

Returned when sending a valid configuration.

sessionId

uuid

required

Returned when sending a valid configuration.

configuration

object

The resolved configuration, including accepted client-defined values and server-applied defaults for parameters not defined in client configuration.

Transcripts

type

string

default:"transcript"

required

Server message indicated recognized speech to text

data

object

required

Show child attributes

text

string

required

Transcript segment with punctuations applied and command phrases removed

rawTranscriptText

string

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

start

float64

Start time of the transcript segment in seconds

end

float64

End time of the transcript segment in seconds

isFinal

boolean

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
    }
}

Click here for detailed guide on how to properly insert transcript segments with proper handling of whitespace, interim vs. final results, and text vs. rawTranscriptText fields.

Commands

type

string

default:"command"

required

Server message indicating a recognized Command

data

object

required

Show child attributes

string

required

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

variables

object

Command variables as key-value pairs

rawTranscriptText

string

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

start

float64

Start time of the transcript segment in seconds

end

float64

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
  }
}

Audio Events

type

string

default:"audioEvent"

Server message indicating an audio quality or speech activity event

data

object

Show child attributes

event

string

required

The type of audio quality or speech activity event.Possible values: speechQualityIssueDetected, speechQualityIssueRecovered, longSilenceDetected, longSilenceRecovered

channel

integer

required

Audio channel identifier

startTimeMs

integer

required

Start time of the event in milliseconds

Audio Event response

{
  "type": "audioEvent",
  "data": {
    "event": "speechQualityIssueDetected",
    "channel": 0,
    "startTimeMs": 4200
  }
}

Flushed

type

string

default:"flushed"

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

{
  "type": "flushed"
}

Usage

type

string

default:"delta-usage"

Returned by server, after processing flush event from client, to convey amount of credits consumed since recording started. Delta usage is approximate and may differ slightly from final usage sent after end message is processed.

{
  "type": "delta_usage",
  "credits": 0.00116
}

type

string

default:"usage"

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

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

Ended

type

string

default:"ended"

required

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

{
  "type": "ended"
}

socket.on("message", (msg) => {
    switch (msg.type) {
        case "transcript":
            console.log("Transcript:", msg.data.text, "final:", msg.data.isFinal);
            break;
        case "command":
            console.log("Command:", msg.data.id, msg.data.variables);
            break;
        case "flushed":
            console.log("Flush complete");
            break;
        case "ended":
            console.log("Session ended");
            socket.close();
            break;
        case "usage":
            console.log("Credits used:", msg.credits);
            break;
        case "error":
            console.error("Server error:", msg.error);
            break;
    }
});

transcribe.TranscribeTranscriptMessage.Subscribe(message =>
{
    Console.WriteLine($"Transcript: {message.Data.Text}");
});

transcribe.TranscribeCommandMessage.Subscribe(message =>
{
    Console.WriteLine($"Command: {message.Data.Id}");
});

transcribe.TranscribeFlushedMessage.Subscribe(_ =>
{
    Console.WriteLine("Flush complete");
});

transcribe.TranscribeEndedMessage.Subscribe(_ =>
{
    Console.WriteLine("Session ended");
});

transcribe.TranscribeUsageMessage.Subscribe(message =>
{
    Console.WriteLine($"Credits used: {message.Credits}");
});

transcribe.TranscribeErrorMessage.Subscribe(message =>
{
    Console.Error.WriteLine($"Server error: {message.Error.Title} ({message.Error.Status})");
});

5. Error Handling

For the full catalog of error codes, real reason strings, and SDK / REST-specific behavior, see the Errors reference.

type

string

required

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

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": {
    "requestid": "<uuid>",
    "details": "error details"
  }
}

Handle errors in SDK

With the recommended approach (passing configuration as part of connect), configuration errors are raised during connect (the call fails). Runtime errors are emitted via the error event; you can also inspect the original message in the message handler.

try {
    const socket = await client.transcribe.connect({
        configuration: {
            primaryLanguage: "en",
            automaticPunctuation: true,
        },
    });

    socket.on("error", (err) => {
        // Network errors and reconnect failures
        console.error("Socket error:", err.message);
    });

    socket.on("message", (msg) => {
        if (msg.type === "error") {
            // Server-sent runtime error
            console.error("Server error:", msg.error);
        }
    });
} catch (err) {
    // CONFIG_DENIED, CONFIG_TIMEOUT, or connection failure
    console.error("Connect failed:", err.message);
}

var transcribe = await client.CreateTranscribeApiAsync();

transcribe.ExceptionOccurred.Subscribe(ex =>
{
    Console.Error.WriteLine($"Socket error: {ex.Message}");
});

transcribe.TranscribeErrorMessage.Subscribe(message =>
{
    Console.Error.WriteLine($"Server error: {message.Error.Title} ({message.Error.Status})");
});

try
{
    await transcribe.ConnectAsync(new TranscribeConfig
    {
        PrimaryLanguage = "en",
        AutomaticPunctuation = true,
    });
}
catch (InvalidOperationException ex)
{
    // CONFIG_DENIED, CONFIG_TIMEOUT, or connection failure
    Console.Error.WriteLine($"Connect failed: {ex.Message}");
    throw;
}

Web Socket APIs

REST APIs

Agentic APIs (beta)

Admin APIs

Corti Models APIs

Errors

Overview

1. Establishing a Connection

Query Parameters

2. Handshake Response

101 Switching Protocols

3. Sending Messages

Configuration

Example

Sending Audio

Flush the Audio Buffer

Ending the Session

4. Responses

Configuration

Transcripts

Commands

Audio Events

Flushed

Usage

Ended

5. Error Handling

Handle errors in SDK

​Overview

​1. Establishing a Connection

​Query Parameters

​2. Handshake Response

​101 Switching Protocols

​3. Sending Messages

​Configuration

​Example

​Sending Audio

​Flush the Audio Buffer

​Ending the Session

​4. Responses

​Configuration

​Transcripts

​Commands

​Audio Events

​Flushed

​Usage

​Ended

​Subscribe to messages in SDK

​5. Error Handling

​Handle errors in SDK

Overview

1. Establishing a Connection

Query Parameters

2. Handshake Response

101 Switching Protocols

3. Sending Messages

Configuration

Example

Sending Audio

Flush the Audio Buffer

Ending the Session

4. Responses

Configuration

Transcripts

Commands

Audio Events

Flushed

Usage

Ended

Subscribe to messages in SDK

5. Error Handling

Handle errors in SDK