> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart - Real-Time AI Scribe
> Learn how to build an ambient scribe application on the Corti API
Follow these steps to get access and start building:
The [Corti Console](https://console.corti.app/) is where you can create an account to access Corti AI
Create an account Create a project Create API clients Use the client ID and client secret in your app Develop against the API and collaborate with your project team Monitor usage, manage billing and more
Authentication to the API on all environments is governed by OAuth 2.0. This authentication protocol offers enhanced security measures, ensuring that access to patient data and medical documentation is securely managed and compliant with healthcare regulations.
By default, you will receive a client-id and client-secret to authenticate via `client credentials` grant type.
To acquire an access token, request a token from Corti Auth using your `client_id` and `client_secret`.
```bash title="cURL (base realm)" theme={null}
# Replace these with your values
CLIENT_ID=""
CLIENT_SECRET=""
ENVIRONMENT=""
curl \
"https://auth.${ENVIRONMENT}.corti.app/realms/base/protocol/openid-connect/token" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d "client_id=${CLIENT_ID}" -d "client_secret=${CLIENT_SECRET}" \
-d 'grant_type=client_credentials' -d 'scope=openid'
```
```bash title="cURL (custom tenant)" theme={null}
# Replace these with your values
CLIENT_ID=""
CLIENT_SECRET=""
ENVIRONMENT=""
TENANT=""
curl \
"https://auth.${ENVIRONMENT}.corti.app/realms/${TENANT}/protocol/openid-connect/token" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d "client_id=${CLIENT_ID}" -d "client_secret=${CLIENT_SECRET}" \
-d 'grant_type=client_credentials' -d 'scope=openid'
```
Create your account and client credentials in the Corti Console - in addition to client ID and client secret you'll see the tenant name and environment.
It will return you an `access_token`:
```json title="Response" theme={null}
{
"access_token": "eyJhbGciOi...",
"expires_in": 300,
"token_type": "Bearer",
"scope": "profile openid email"
}
```
As you can see, the access token expires after 300 seconds (5 minutes). By default as per oAuth standards, no refresh token is used in this flow. There are many available modules to manage monitoring expiry and acquiring a new access token. However, a refresh token can be enabled if needed.
Example **authentication code snippets** for the Corti API in Python, JavaScript, and .NET.
#### With SDK
Install SDK to your project:
```bash title="JavaScript" theme={null}
npm install @corti/sdk
# or
yarn add @corti/sdk
# or
pnpm add @corti/sdk
```
```bash title="C# .NET" theme={null}
dotnet add package Corti.Sdk
# Alternatively, in your .csproj:
#
```
Create a client to call API:
```ts title="JavaScript" theme={null}
import { CortiClient } from "@corti/sdk";
// Replace these with your values
const CLIENT_ID = "";
const CLIENT_SECRET = "";
const ENVIRONMENT = "";
const TENANT = "";
const client = new CortiClient({
environment: ENVIRONMENT,
tenantName: TENANT,
auth: {
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
},
});
```
```csharp title="C# .NET" theme={null}
using Corti;
// Replace these with your values
const string CLIENT_ID = "";
const string CLIENT_SECRET = "";
const string ENVIRONMENT = "";
const string TENANT = "";
var client = new CortiClient(
tenantName: TENANT,
environment: ENVIRONMENT,
auth: CortiClientAuth.ClientCredentials(
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET)
);
```
If you only need a token:
```ts title="JavaScript" theme={null}
import { CortiAuth } from "@corti/sdk";
// Replace these with your values
const CLIENT_ID = "";
const CLIENT_SECRET = "";
const ENVIRONMENT = "";
const TENANT = "";
const auth = new CortiAuth({
environment: ENVIRONMENT,
tenantName: TENANT,
});
const token = await auth.getToken({
clientId: CLIENT_ID,
clientSecret: CLIENT_SECRET,
});
console.log("accessToken:", token.accessToken);
```
{/* Get a token via client credentials using CustomAuthClient */}
```csharp title="C# .NET" theme={null}
using Corti;
// Replace these with your values
const string CLIENT_ID = "";
const string CLIENT_SECRET = "";
const string ENVIRONMENT = "";
const string TENANT = "";
var auth = CustomAuthClient.Create(
new CortiAuthClientOptions
{
TenantName = TENANT,
Environment = ENVIRONMENT,
});
var tokenResponse = await auth.GetTokenAsync(
new OAuthTokenRequest
{
ClientId = CLIENT_ID,
ClientSecret = CLIENT_SECRET,
});
Console.WriteLine(tokenResponse.AccessToken);
```
#### Without SDK
```js title="JavaScript" expandable theme={null}
// Replace these with your values
const CLIENT_ID = "";
const CLIENT_SECRET = "";
const ENVIRONMENT = "";
const TENANT = "";
async function getAccessToken() {
const tokenUrl = `https://auth.${ENVIRONMENT}.corti.app/realms/${TENANT}/protocol/openid-connect/token`;
const params = new URLSearchParams();
params.append("client_id", CLIENT_ID);
params.append("client_secret", CLIENT_SECRET);
params.append("grant_type", "client_credentials");
params.append("scope", "openid");
const res = await fetch(tokenUrl, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: params
});
if (!res.ok) {
throw new Error(`Failed to get token, status ${res.status}`);
}
const data = await res.json();
return data.access_token;
}
// Example usage
getAccessToken().then(token => {
console.log("Access token:", token);
}).catch(err => {
console.error("Error:", err);
});
```
```csharp title="C# .NET" expandable theme={null}
using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
private const string CLIENT_ID = "";
private const string CLIENT_SECRET = "";
private const string ENVIRONMENT = "";
private const string TENANT = "";
private static async Task GetAccessTokenAsync()
{
var tokenUrl = $"https://auth.{ENVIRONMENT}.corti.app/realms/{TENANT}/protocol/openid-connect/token";
using var http = new HttpClient();
var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair("client_id", CLIENT_ID),
new KeyValuePair("client_secret", CLIENT_SECRET),
new KeyValuePair("grant_type", "client_credentials"),
new KeyValuePair("scope", "openid")
});
var response = await http.PostAsync(tokenUrl, content);
response.EnsureSuccessStatusCode();
var payload = await response.Content.ReadAsStringAsync();
using var json = JsonDocument.Parse(payload);
return json.RootElement.GetProperty("access_token").GetString()!;
}
static async Task Main()
{
var token = await GetAccessTokenAsync();
Console.WriteLine($"Access token: {token}");
}
}
```
```python title="Python" expandable theme={null}
import requests
# Replace these with your values
CLIENT_ID = ""
CLIENT_SECRET = ""
ENVIRONMENT = ""
TENANT = ""
def get_access_token():
"""Request an OAuth2 client-credentials access token from Corti."""
url = f"https://auth.{ENVIRONMENT}.corti.app/realms/{TENANT}/protocol/openid-connect/token"
data = {
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"grant_type": "client_credentials",
"scope": "openid",
}
res = requests.post(url, data=data, headers={"Content-Type": "application/x-www-form-urlencoded"})
res.raise_for_status()
return res.json()["access_token"]
# Example usage
if __name__ == "__main__":
token = get_access_token()
print("Access token:", token)
```
```bash title="cURL" theme={null}
# Replace these with your values
CLIENT_ID=""
CLIENT_SECRET=""
ENVIRONMENT=""
TENANT=""
curl "https://auth.${ENVIRONMENT}.corti.app/realms/${TENANT}/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=${CLIENT_ID}" \
-d "client_secret=${CLIENT_SECRET}" \
-d "grant_type=client_credentials" \
-d "scope=openid"
```
Once you're authenticated, make requests against the API. Below is a basic example for creating an Interaction. See all API requests and specifications [here](/api-reference/).
### With SDK
REST API:
```ts title="JavaScript" theme={null}
// Token acquisition and refresh happen automatically
const interactions = await client.interactions.list();
```
{/* List interactions with async foreach pagination */}
```csharp title="C# .NET" theme={null}
var pager = await client.Interactions.ListAsync(new InteractionsListRequest());
```
```python title="Python" theme={null}
import requests
# Replace these with your values
ENVIRONMENT = ""
TENANT = ""
TOKEN = ""
response = requests.get(
f"https://api.{ENVIRONMENT}.corti.app/v2/interactions",
headers={
"Authorization": f"Bearer {TOKEN}",
"Tenant-Name": TENANT,
},
)
response.raise_for_status()
interactions = response.json()["interactions"]
```
```bash title="cURL" theme={null}
# Replace these with your values
ENVIRONMENT=""
TENANT=""
TOKEN=""
curl "https://api.${ENVIRONMENT}.corti.app/v2/interactions" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Tenant-Name: ${TENANT}"
```
WebSockets:
```ts title="JavaScript" theme={null}
const streamSocket = await client.stream.connect({
id: ""
});
```
{/* Connect to /streams without configuration */}
```csharp title="C# .NET" theme={null}
var stream = await client.CreateStreamApiAsync("");
await stream.ConnectAsync();
```
### Without SDK
Subsequently you use the `access_token` to authenticate any API request. The baseURL is dependent on the environment:
```bash baseURL API theme={null}
api.$environment.corti.app/v2
```
Create your account and client credentials in the Corti Console - in addition to client ID and client secret you'll see the tenant name and environment.
If, for example, you are on the eu environment and want to create an interaction as the starting point for any other workflow operations your URL will look like this:
```bash URL to create an interaction theme={null}
POST https://api.eu.corti.app/v2/interactions/
```
For **REST API requests**, your `access_token` should be passed as part of the `Request Header`. Additionally you need to include the `Tenant-Name` parameter:
```jsx API call request header theme={null}
Tenant-Name:
Authorization: Bearer
```
Create your account and client credentials in the Corti Console - in addition to client ID and client secret you'll see the tenant name and environment.
For **WebSocket** connections, the `access_token` should be passed in as URL parameter. The `Tenant-Name` is already part of the WebSocket url returned with the create interaction request:
```javascript wss url with access_token appended theme={null}
wss://{streams-url}&token=Bearer {access_token}
```
Find the full specification for create interaction request in the [API Reference](api-reference/interactions/create-interaction)
```js title="JavaScript" theme={null}
import { createReadStream } from "node:fs";
import { randomUUID } from "node:crypto";
import { CortiClient } from "@corti/sdk";
const client = new CortiClient({
environment: "",
tenantName: "",
auth: {
clientId: "",
clientSecret: "",
},
});
const audioPath = "sample.mp3";
const now = new Date();
const { interactionId } = await client.interactions.create({
assignedUserId: randomUUID(),
encounter: {
identifier: randomUUID(),
status: "planned",
type: "first_consultation",
period: {
startedAt: now,
endedAt: now,
},
title: "Consultation",
},
});
if (!interactionId) throw new Error("Missing interactionId");
const streamSocket = await client.stream.connect({
id: interactionId,
configuration: {
transcription: {
primaryLanguage: "en",
isDiarization: false,
isMultichannel: false,
participants: [{ channel: 0, role: "multiple" }],
},
mode: { type: "facts", outputLocale: "en" },
},
});
streamSocket.on("message", (message) => {
if (message.type === "facts") {
console.log("Facts:", message);
} else if (message.type === "transcript") {
console.log("Transcript:", message);
} else if (message.type === "error") {
console.error("Error:", message);
} else if (message.type === "ENDED") {
console.log("ENDED");
}
});
const audioStream = createReadStream(audioPath, { highWaterMark: 32000 });
for await (const chunk of audioStream) {
streamSocket.sendAudio(chunk);
}
streamSocket.sendEnd({ type: "end" });
```
```csharp title="C# .NET" theme={null}
using Corti;
var client = new CortiClient(
tenantName: "",
environment: "",
auth: CortiClientAuth.ClientCredentials(
clientId: "",
clientSecret: "")
);
var audioPath = "sample.mp3";
var now = DateTime.UtcNow;
var interaction = await client.Interactions.CreateAsync(
new InteractionsCreateRequest
{
AssignedUserId = Guid.NewGuid().ToString(),
Encounter = new InteractionsEncounterCreateRequest
{
Identifier = Guid.NewGuid().ToString(),
Status = InteractionsEncounterStatusEnum.Planned,
Type = InteractionsEncounterTypeEnum.FirstConsultation,
Period = new InteractionsEncounterPeriod
{
StartedAt = now,
EndedAt = now,
},
Title = "Consultation",
},
}
);
await using var stream = await client.CreateStreamApiAsync(interaction.InteractionId);
stream.StreamFactsMessage.Subscribe(message =>
{
Console.WriteLine(message);
});
stream.StreamErrorMessage.Subscribe(message =>
{
Console.Error.WriteLine($"Error: {message.Error.Title} ({message.Error.Status})");
});
stream.StreamEndedMessage.Subscribe(_ =>
{
Console.WriteLine("ENDED");
});
await stream.ConnectAsync(new StreamConfig
{
Transcription = new StreamConfigTranscription
{
PrimaryLanguage = "en",
IsDiarization = false,
IsMultichannel = false,
Participants = new List
{
new() { Channel = 0, Role = StreamConfigParticipantRole.Multiple },
},
},
Mode = new StreamConfigMode
{
Type = StreamConfigModeType.Facts,
OutputLocale = "en",
},
});
await using var audioStream = File.OpenRead(audioPath);
var buffer = new byte[32000];
int bytesRead;
while ((bytesRead = await audioStream.ReadAsync(buffer)) > 0)
{
if (bytesRead == buffer.Length)
{
await stream.Send(buffer);
}
else
{
var chunk = new byte[bytesRead];
Buffer.BlockCopy(buffer, 0, chunk, 0, bytesRead);
await stream.Send(chunk);
}
}
await stream.Send(new StreamEndMessage());
```
```py title="Python" theme={null}
import os
import json
import time
import uuid
import requests
import websocket
from urllib.parse import quote
from datetime import datetime, timezone
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
CLIENT_ID = os.getenv("CLIENT_ID")
CLIENT_SECRET = os.getenv("CLIENT_SECRET")
TENANT_NAME = os.getenv("TENANT_NAME")
ENVIRONMENT = os.getenv("ENVIRONMENT")
def get_access_token():
print("🔐 Step 1 — Authenticating...")
url = f"https://auth.{ENVIRONMENT}.corti.app/realms/{TENANT_NAME}/protocol/openid-connect/token"
payload = {
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"scope": "openid"
}
headers = {"Content-Type": "application/x-www-form-urlencoded"}
response = requests.post(url, data=payload, headers=headers)
if response.ok:
print("✅ Authenticated")
return response.json()["access_token"]
raise Exception(f"Authentication failed: {response.status_code} - {response.text}")
def create_interaction(token):
print("🔗 Step 2 — Creating interaction session...")
url = f"https://api.{ENVIRONMENT}.corti.app/v2/interactions"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"Tenant-Name": TENANT_NAME
}
now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
payload = {
"assignedUserId": str(uuid.uuid4()),
"encounter": {
"identifier": str(uuid.uuid4()),
"status": "planned",
"type": "first_consultation",
"period": {
"startedAt": now,
"startedAtTzoffset": "+00:00",
"endedAt": now,
"endedAtTzoffset": "+00:00"
},
"title": "Consultation"
}
}
response = requests.post(url, json=payload, headers=headers)
if response.ok:
print("✅ Interaction session created")
return response.json()
raise Exception(f"Interaction creation failed: {response.status_code} - {response.text}")
def stream_audio(ws, path):
print("🎧 Step 4 — Streaming audio...")
chunk_size = 32000
with open(path, "rb") as f:
while chunk := f.read(chunk_size):
ws.send(chunk, opcode=websocket.ABNF.OPCODE_BINARY)
time.sleep(0.5)
ws.send(json.dumps({"type": "end"}))
print("✅ Audio stream completed")
def connect_and_stream_audio(ws_url, audio_path):
print("🌐 Step 3 — Connecting to WebSocket and sending config...")
transcript_lines = []
def on_open(ws):
config = {
"type": "config",
"configuration": {
"transcription": {
"primaryLanguage": "en",
"isDiarization": False,
"isMultichannel": False,
"participants": [{"channel": 0, "role": "multiple"}]
},
"mode": {"type": "facts", "outputLocale": "en"}
}
}
ws.send(json.dumps(config))
print("✅ Configuration sent")
def on_message(ws, message):
msg = json.loads(message)
msg_type = msg.get("type").upper()
if msg_type == "CONFIG_ACCEPTED":
print("🟢 Config accepted by server")
stream_audio(ws, audio_path)
elif msg_type == "TRANSCRIPT":
print("📄Step 5 -Transcript received:")
content = " ".join([x["transcript"] for x in msg["data"]])
if content:
transcript_lines.append(content)
elif msg_type == "FACTS":
print("📄Step 5 - Facts received:")
print(json.dumps(msg, indent=2))
elif msg_type == "ENDED":
print("📌 Step 6 — Session ended by server")
if transcript_lines:
print("\n📝 Final Transcript:")
for line in transcript_lines:
print(line)
else:
print("⚠️ No transcript received.")
ws.close()
def on_close(ws, code, reason):
print("✅ WebSocket closed")
websocket.enableTrace(False)
ws = websocket.WebSocketApp(
ws_url,
on_open=on_open,
on_message=on_message,
on_error=lambda ws, err: print(f"[ERROR] {err}"),
on_close=on_close
)
ws.run_forever()
def main(audio_path):
if not os.path.isfile(audio_path):
raise FileNotFoundError(f"Missing file: {audio_path}")
token = get_access_token()
interaction = create_interaction(token)
print("\n📦 Final interaction response:")
print(json.dumps(interaction, indent=2))
ws_url = interaction.get("websocketUrl")
if not ws_url:
raise ValueError("Missing WebSocket URL in response")
ws_url += f"&token={quote(f'Bearer {token}')}"
connect_and_stream_audio(ws_url, audio_path)
if __name__ == "__main__":
audio_file_path = "PATH_TO_FILE.wav"
main(audio_file_path)
```
For support or questions, please reach out via [help.corti.app](https://help.corti.app).
To get access to Corti API [click here to sign up](https://console.corti.app/signup)