Corti.Sdk package exports two main entry points:
| Export | Namespace | Purpose |
|---|---|---|
CortiClient | using Corti; | Full API client with all resource groups, authentication, and WebSockets |
CustomAuthClient | using Corti; | Standalone authentication client for token management and OAuth flows |
CortiClient
The main client for all Corti API operations.Constructors
CortiEnvironmentInput accepts a region string, a CortiClientEnvironment, or CortiEnvironments.FromBaseUrl(...) via implicit conversion.
Overload 2 decodes tenant and environment from the access token JWT. If the token cannot be decoded, use overload 1 instead.
Overload 3 sends no Authorization header. CreateStreamApiAsync / CreateTranscribeApiAsync require a tenant and will throw. See Proxy / passthrough.
CortiRequestOptions
| Property | Type | Default | Description |
|---|---|---|---|
MaxRetries | int? | 2 | Number of automatic retries on 408, 429, and 5xx |
Timeout | TimeSpan? | 30s | Default request timeout |
HttpClient | HttpClient? | null | Custom HttpClient instance |
AdditionalHeaders | IEnumerable<KeyValuePair<string, string?>>? | null | Headers sent with every request |
Request options
Every HTTP method accepts an optionalRequestOptions parameter:
C# .NET
| Property | Type | Description |
|---|---|---|
BaseUrl | string? | Override the base URL for this request |
HttpClient | HttpClient? | Override the HttpClient for this request |
MaxRetries | int? | Override the default retry count |
Timeout | TimeSpan? | Override the default timeout |
AdditionalHeaders | IEnumerable<KeyValuePair<string, string?>> | Additional HTTP headers |
AdditionalQueryParameters | IEnumerable<KeyValuePair<string, string>> | Additional query string parameters |
AdditionalBodyProperties | object? | Additional JSON properties merged into the request body |
Resource groups
The client exposes the following resource groups as properties:| Group | Description | API endpoints |
|---|---|---|
client.Interactions | Manage patient encounters and interaction sessions | Interactions API |
client.Recordings | Upload and retrieve audio recordings for interactions | Recordings API |
client.Transcripts | Create and retrieve transcriptions of recordings | Transcripts API |
client.Documents | Generate and manage AI-produced clinical documents | Documents API |
client.Facts | Extract and manage structured clinical facts | Facts API |
client.Templates | List and retrieve document generation templates | Templates API |
client.Codes | Predict medical codes from clinical data | Codes API |
client.Agents | Create and interact with AI agents | Agents API |
client.Auth | OAuth token management and authorization URLs | Auth API |
| Method | Description | API endpoint |
|---|---|---|
CreateStreamApiAsync(interactionId) | Real-time WebSocket streaming (transcription + facts) | Stream API |
CreateTranscribeApiAsync() | Real-time WebSocket speech-to-text (standalone) | Transcribe API |
Interactions
Manage interaction sessions that group recordings, transcripts, documents, and facts together.C# .NET
| Method | Parameters | Returns |
|---|---|---|
ListAsync(request) | Filter and pagination options | Pager (async enumerable) |
CreateAsync(request) | Interaction definition | Created interaction |
GetAsync(id) | Interaction UUID | Single interaction |
UpdateAsync(id, request?) | Interaction UUID + update fields | Updated interaction |
DeleteAsync(id) | Interaction UUID | void |
Recordings
Upload and manage audio recordings within an interaction.C# .NET
| Method | Parameters | Returns |
|---|---|---|
UploadAsync(interactionId, file) | Interaction UUID + file stream | Created recording |
ListAsync(interactionId) | Interaction UUID | List of recordings |
GetAsync(interactionId, recordingId) | Interaction UUID + recording UUID | Audio stream |
DeleteAsync(interactionId, recordingId) | Interaction UUID + recording UUID | void |
Transcripts
Create transcriptions from uploaded recordings and retrieve results.C# .NET
| Method | Parameters | Returns |
|---|---|---|
CreateAsync(interactionId, request) | Interaction UUID + transcript definition | Created transcript |
GetStatusAsync(interactionId, transcriptId) | Interaction UUID + transcript UUID | Transcription status |
ListAsync(interactionId, request?) | Interaction UUID + optional filters | List of transcripts |
GetAsync(interactionId, transcriptId) | Interaction UUID + transcript UUID | Single transcript |
DeleteAsync(interactionId, transcriptId) | Interaction UUID + transcript UUID | void |
Documents
Generate AI-produced clinical documents (e.g. SOAP notes) from interaction data.C# .NET
| Method | Parameters | Returns |
|---|---|---|
CreateAsync(interactionId, request) | Interaction UUID + document generation options | Generated document |
ListAsync(interactionId) | Interaction UUID | List of documents |
GetAsync(interactionId, documentId) | Interaction UUID + document UUID | Single document |
UpdateAsync(interactionId, documentId, request?) | Interaction UUID + document UUID + update fields | Updated document |
DeleteAsync(interactionId, documentId) | Interaction UUID + document UUID | void |
Facts
Extract structured clinical facts from text or manage facts on an interaction.C# .NET
| Method | Parameters | Returns |
|---|---|---|
ExtractAsync(request) | Extraction options (context, output language) | Extracted facts |
ListAsync(interactionId) | Interaction UUID | List of facts |
CreateAsync(interactionId, request) | Interaction UUID + fact definitions | Created facts |
BatchUpdateAsync(interactionId, request) | Interaction UUID + fact updates | Updated facts |
UpdateAsync(interactionId, factId, request?) | Interaction UUID + fact ID + update fields | Updated fact |
FactGroupsListAsync() | None | Available fact group definitions |
Templates
List and inspect document generation templates available to your tenant.C# .NET
| Method | Parameters | Returns |
|---|---|---|
ListAsync(request) | List filters | List of templates |
GetAsync(key) | Template key string | Single template |
SectionListAsync(request) | Section list filters | List of template sections |
Codes
Predict medical codes from clinical data.C# .NET
| Method | Parameters | Returns |
|---|---|---|
PredictAsync(request) | CodesGeneralPredictRequest (text, code system) | Code predictions |
Agents
Create and interact with AI agents (Agentic Framework).C# .NET
| Method | Parameters | Returns |
|---|---|---|
ListAsync(request) | List filters | List of agents |
CreateAsync(request) | Agent definition | Created agent |
GetAsync(id) | Agent ID | Agent details |
GetCardAsync(id) | Agent ID | Agent card (A2A format) |
MessageSendAsync(id, request) | Agent ID + message payload | Agent response |
GetTaskAsync(id, taskId, request?) | Agent ID + task ID | Task details |
GetContextAsync(id, contextId, request?) | Agent ID + context ID | Context details |
GetRegistryExpertsAsync(request?) | Optional filters | Registry experts |
UpdateAsync(id, request?) | Agent ID + update fields | Updated agent |
DeleteAsync(id) | Agent ID | void |
Stream
Real-time WebSocket connection for combined transcription, fact extraction, and more — tied to an interaction.C# .NET
Factory method
| Parameter | Type | Required | Description |
|---|---|---|---|
interactionId | string | Yes | Interaction UUID to attach the stream to |
Task<IStreamApi>.
ConnectAsync parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
configuration | StreamConfig | No | Stream configuration (language, participants, mode). When provided, the SDK automatically sends the config message once the socket opens and waits for CONFIG_ACCEPTED. If omitted, you must send a config message yourself |
cancellationToken | CancellationToken | No | Cancellation support |
Events
Subscribe to events using the.Subscribe() method on each Event<T> field:
| Event | Type | Description |
|---|---|---|
Connected | Event<Connected> | WebSocket connection established |
Closed | Event<Closed> | WebSocket connection closed |
ExceptionOccurred | Event<Exception> | WebSocket error occurred |
Reconnecting | Event<ReconnectionInfo> | Reconnection attempt in progress |
StreamTranscriptMessage | Event<StreamTranscriptMessage> | Transcript data received |
StreamFactsMessage | Event<StreamFactsMessage> | Facts data received |
StreamFlushedMessage | Event<StreamFlushedMessage> | Audio buffer flushed |
StreamEndedMessage | Event<StreamEndedMessage> | Stream session ended |
StreamUsageMessage | Event<StreamUsageMessage> | Usage metrics |
StreamDeltaUsageMessage | Event<StreamDeltaUsageMessage> | Incremental usage metrics |
StreamErrorMessage | Event<StreamErrorMessage> | Server-side error |
StreamConfigStatusMessage | Event<StreamConfigStatusMessage> | Config accepted or denied |
UnknownMessage | Event<JsonElement> | Unrecognised message type |
Methods
| Method | Description |
|---|---|
ConnectAsync(configuration?, cancellationToken?) | Open the WebSocket connection |
Send(byte[]) | Send binary audio data |
Send(StreamFlushMessage) | Request the server to flush buffered audio |
Send(StreamEndMessage) | Signal end of audio stream |
Send(StreamConfigMessage) | Send a configuration message manually |
CloseAsync(cancellationToken?) | Close the connection. Call Send(new StreamEndMessage()) first and wait for StreamEndedMessage |
DisposeAsync() | Dispose the WebSocket resources |
Transcribe
Real-time WebSocket speech-to-text without an interaction context.C# .NET
ConnectAsync parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
configuration | TranscribeConfig | No | Transcribe configuration (language, punctuation, commands). When provided, the SDK automatically sends the config message once the socket opens and waits for CONFIG_ACCEPTED. If omitted, you must send a config message yourself |
cancellationToken | CancellationToken | No | Cancellation support |
Events
| Event | Type | Description |
|---|---|---|
Connected | Event<Connected> | WebSocket connection established |
Closed | Event<Closed> | WebSocket connection closed |
ExceptionOccurred | Event<Exception> | WebSocket error occurred |
Reconnecting | Event<ReconnectionInfo> | Reconnection attempt in progress |
TranscribeTranscriptMessage | Event<TranscribeTranscriptMessage> | Transcript data received |
TranscribeCommandMessage | Event<TranscribeCommandMessage> | Command detected |
TranscribeFlushedMessage | Event<TranscribeFlushedMessage> | Audio buffer flushed |
TranscribeEndedMessage | Event<TranscribeEndedMessage> | Session ended |
TranscribeUsageMessage | Event<TranscribeUsageMessage> | Usage metrics |
TranscribeDeltaUsageMessage | Event<TranscribeDeltaUsageMessage> | Incremental usage metrics |
TranscribeErrorMessage | Event<TranscribeErrorMessage> | Server-side error |
TranscribeConfigStatusMessage | Event<TranscribeConfigStatusMessage> | Config accepted or denied |
UnknownMessage | Event<JsonElement> | Unrecognised message type |
Methods
| Method | Description |
|---|---|
ConnectAsync(configuration?, cancellationToken?) | Open the WebSocket connection |
Send(byte[]) | Send binary audio data |
Send(TranscribeFlushMessage) | Request the server to flush buffered audio |
Send(TranscribeEndMessage) | Signal end of audio stream |
Send(TranscribeConfigMessage) | Send a configuration message manually |
CloseAsync(cancellationToken?) | Close the connection. Call Send(new TranscribeEndMessage()) first and wait for TranscribeEndedMessage |
DisposeAsync() | Dispose the WebSocket resources |
- No interaction ID — Transcribe operates standalone via
CreateTranscribeApiAsync()(nointeractionIdparameter) - Different message types — Transcribe delivers transcript, command, flushed, ended, usage,
delta_usage, and error messages, while Stream delivers transcript, facts, flushed, ended, usage,delta_usage, and error
Auth
OAuth token management viaclient.Auth. In most cases you won’t call these directly — the SDK handles tokens automatically based on the auth option you pass to the constructor. These methods are useful for advanced scenarios like generating authorization URLs for browser-based flows.
| Method | Description |
|---|---|
GetTokenAsync(OAuthTokenRequest) | Get a token via client credentials |
GetTokenAsync(OAuthRopcTokenRequest) | Get a token via ROPC flow |
GetTokenAsync(OAuthAuthCodeTokenRequest) | Exchange an authorization code for a token |
GetTokenAsync(OAuthPkceTokenRequest) | Exchange a PKCE code for a token |
GetTokenAsync(OAuthRefreshTokenRequest) | Refresh an expired token |
AuthorizeUrlAsync(clientId, redirectUri, ...) | Generate an authorization URL |
GetTokenAsync overloads also accept *WithScopes request variants (e.g. OAuthTokenRequestWithScopes) to request scoped tokens.
CustomAuthClient
A standalone authentication client for when you need OAuth token management without the fullCortiClient. Useful for proxy servers, custom backends, or applications that handle tokens separately from API calls.
C# .NET
Constructor options
| Property | Type | Required | Description |
|---|---|---|---|
TenantName | string | Yes | Your Corti tenant name |
Environment | string | CortiClientEnvironment | Yes | API region or custom environment |
RequestOptions | CortiRequestOptions? | No | Default request options |
Methods
| Method | Description | Returns |
|---|---|---|
GetTokenAsync(OAuthTokenRequest) | Get a token via client credentials | AuthTokenResponse |
GetTokenAsync(OAuthRopcTokenRequest) | Get a token via ROPC flow | AuthTokenResponse |
GetTokenAsync(OAuthAuthCodeTokenRequest) | Exchange an authorization code for a token | AuthTokenResponse |
GetTokenAsync(OAuthPkceTokenRequest) | Exchange a PKCE code for a token | AuthTokenResponse |
GetTokenAsync(OAuthRefreshTokenRequest) | Refresh an expired token | AuthTokenResponse |
AuthorizeUrlAsync(clientId, redirectUri, codeChallenge?, scopes?) | Generate an authorization URL | string |
GetTokenAsync overloads also accept *WithScopes request variants to request scoped tokens.
Authentication types
TheCortiClientAuth abstract record has the following concrete variants used with the CortiClient constructor:
| Variant | Parameters | Description |
|---|---|---|
CortiClientAuth.ClientCredentials | clientId, clientSecret | Server-to-server (guide) |
CortiClientAuth.AuthorizationCode | clientId, clientSecret, code, redirectUri | Interactive login (guide) |
CortiClientAuth.Pkce | clientId, code, redirectUri, codeVerifier | Public client login (guide) |
CortiClientAuth.Ropc | clientId, username, password | Username/password (guide) |
CortiClientAuth.Bearer | accessToken, clientId?, refreshToken?, expiresIn?, refreshExpiresIn?, refreshAccessToken? | Existing token (guide) |
CortiClientAuth.BearerCustomRefresh | refreshAccessToken, accessToken?, expiresIn?, refreshToken?, refreshExpiresIn? | Custom refresh logic (guide) |
Error handling
The SDK throws typed exceptions you can catch and inspect:C# .NET
| Exception | Status code | When it’s thrown |
|---|---|---|
BadRequestError | 400 | Malformed request |
UnauthorizedError | 401 | Missing or invalid authentication |
ForbiddenError | 403 | Insufficient permissions |
NotFoundError | 404 | Resource not found |
UnprocessableEntityError | 422 | Validation failed (includes AgentsValidationErrorResponse body) |
InternalServerError | 500 | Server error |
BadGatewayError | 502 | Gateway error |
GatewayTimeoutError | 504 | Gateway timeout |
CortiClientApiException, which inherits from CortiClientException.
Environments
UseCortiEnvironments to create custom environments:
C# .NET
| Method | Description |
|---|---|
FromRegion(region) | Create an environment from a region string |
FromBaseUrl(baseUrl) | Create an environment pointing at a custom proxy URL |