Quickstart — Real-time & Asynchronous

Completing this quickstart will get you an end-to-end text generation flow — from audio (or an uploaded recording) all the way to a guided-synthesized clinical note. Both scenarios build on Corti’s official SDKs and end with the same Guided Documents call.

Prerequisites

A Corti Console account with an API client — if you haven’t set one up yet, follow Creating API Clients and the Authentication Quickstart. You’ll need your clientId, clientSecret, tenantName, and environment (eu or us).
The Corti SDK installed and a client created — install (@corti/sdk or Corti.Sdk) and initialize a client by following the Authentication Quickstart or the SDKs overview. The SDK handles OAuth 2.0 token acquisition and refresh from your credentials automatically — no manual bearer-token juggling.
A templateId — the UUID of a stored template to synthesize the note against. Discover Corti Standards or your own via LIST /documents/templates?lang=<locale>, or browse Corti Standards.

Pick your scenario

Both scenarios end with the same guided document generation call. They differ only in how audio is captured and turned into a transcript.

Real-time ambient scribe
Asynchronous

Create an interaction

An interaction anchors the session — the transcript and facts your stream produces are persisted under it, and the doc-gen step reads them back.

// Replace with an identifier of your choosing
const IDENTIFIER = "<id-of-your-choosing>";

const { interactionId } = await client.interactions.create({
  encounter: {
    identifier: IDENTIFIER,
    status: "planned",
    type: "first_consultation",
  },
});

Only encounter (with identifier, status, and type) is required. assignedUserId, patient, period, and title are optional — see Create Interaction for the full schema.

Capture and stream audio in real time

For live capture in the browser, the Ambient Web Component (@corti/ambient-web) is the fastest path — the <corti-ambient> element handles microphone permissions, device selection, audio streaming, and transcript/facts delivery for you. Point it at the interactionId from step 1 and configure it for facts (real-time extraction).

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Corti Ambient</title>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@corti/ambient-web/dist/bundle.js"></script>
</head>
<body>
    <corti-ambient id="ambient" interactionId="<your-interaction-id>"></corti-ambient>

    <script>
        const ambient = document.getElementById("ambient");

        ambient.addEventListener("ready", () => {
            ambient.accessToken = "<your-access-token>";
            ambient.ambientConfig = {
                transcription: { primaryLanguage: "en" },
                mode: { type: "facts", outputLocale: "en" },
            };
        });

        ambient.addEventListener("transcript", (event) => {
            // Segments can arrive out of order across speakers — order by time.start
            [...event.detail.data]
                .sort((a, b) => a.time.start - b.time.start)
                .forEach((seg) => {
                    console.log(`[${seg.time.start}s → ${seg.time.end}s]: ${seg.transcript}`);
                });
        });

        ambient.addEventListener("facts", (event) => {
            event.detail.fact.forEach((fact) => {
                console.log(`Fact [${fact.group}]: ${fact.text}`);
            });
        });
    </script>
</body>
</html>

The web component does not manage OAuth — supply an accessToken (or a token-refresh function); see the Ambient authentication guide. In production you’d create the interaction server-side and pass the interactionId and token to the browser.

The component persists transcripts and (with mode.type: "facts") extracted facts under the interaction — that’s the data the doc-gen step reasons over. Before generating the note, wait until recording has stopped and audio processing has finished (recording-state-changed reports detail.processing: false, or call closeConnection(), which sends end and waits for the server’s ended response) so every transcript segment and fact is stored.

Streaming audio from your own pipeline — server-side, or a non-browser client? Skip the web component and use the lower-level client.stream.connect() + sendAudio() methods from the JavaScript or .NET SDK. See the SDKs overview for the full menu.

Generate a note from the interaction

Once the session has ended, generate the note by referencing the interactionId — the SDK pulls the persisted facts and transcript implicitly. templateRef picks the template you want.

// Replace these with your values
const INTERACTION_ID = "<your-interaction-id>";
const TEMPLATE_ID = "<your-template-id>";

const result = await client.documents.generate({
  outputLanguage: "en-US",
  interactionId: INTERACTION_ID,
  templateRef: { templateId: TEMPLATE_ID },
});

This is Path 1 — plain templateRef of Guided Document Synthesis. For per-user tweaks (Path 2), runtime section assembly (Path 3), or inline definitions (Path 4), see the four paths.

Full specification: Generate a structured document.

Create an interaction

// Replace with an identifier of your choosing
const IDENTIFIER = "<id-of-your-choosing>";

const { interactionId } = await client.interactions.create({
  encounter: {
    identifier: IDENTIFIER,
    status: "planned",
    type: "first_consultation",
  },
});

Only encounter (with identifier, status, and type) is required. assignedUserId, patient, period, and title are optional — see Create Interaction for the full schema.

Upload the recording

Attach the audio file to the interaction.

import { createReadStream } from "fs";

// Replace these with your values
const INTERACTION_ID = "<your-interaction-id>";

const file = createReadStream("sample.mp3", { autoClose: true });
await client.recordings.upload(file, INTERACTION_ID);

Full specification: Upload Recording.

Generate a transcript

Kick off transcription for the uploaded recording. You’ll need the interactionId from step 1 and the recordingId from step 2.

const { recordingId } = await uploadRecording(client, interactionId, "sample.mp3");

const transcript = await client.transcripts.create(interactionId, {
    recordingId: recordingId,
    primaryLanguage: "en"
});

Full specification: Create Transcript.

Extract and store facts (optional)

Guided doc-gen already reasons over the transcript. To also ground it on structured facts — the same signal the real-time path captures automatically — extract them from the transcript text with tools/extract-facts.

// Replace with your transcript text (e.g. the transcript segments from the previous step, joined)
const TRANSCRIPT_TEXT = "<your-transcript-text>";

const { facts } = await client.facts.extract({
  context: [{ type: "text", text: TRANSCRIPT_TEXT }],
  outputLanguage: "en",
});

tools/extract-facts is stateless — it returns facts but does not persist them. To make them available to guided document generation (which reads facts stored under the interaction), write them back with POST /interactions/{id}/facts.

// Replace these with your values
const INTERACTION_ID = "<your-interaction-id>";

await client.facts.create(INTERACTION_ID, {
  facts: [
    {
      text: "Patient has a history of hypertension.",
      group: "other",
    },
  ],
});

Full specifications: Extract Facts and Add Facts.

Generate a note from the interaction

Same as the real-time path — reference the interactionId and a templateId. The SDK pulls the persisted transcript (and any facts) implicitly.

// Replace these with your values
const INTERACTION_ID = "<your-interaction-id>";
const TEMPLATE_ID = "<your-template-id>";

const result = await client.documents.generate({
  outputLanguage: "en-US",
  interactionId: INTERACTION_ID,
  templateRef: { templateId: TEMPLATE_ID },
});

Full specification: Generate a structured document.

What you get back

Guided document generation returns a document plus usageInfo:

{
  "document": {
    "id": "<your-document-id>",
    "templateId": "<your-template-id>",
    "templateVersionId": "<your-version-id>",
    "language": "en-US",
    "stringDocument": {
      "<your-section-id>": "History of present illness paragraph...",
      "<your-section-id>": "- Item 1\n- Item 2\n..."
    },
    "structuredDocument": null,
    "createdAt": "2026-05-20T10:00:00Z",
    "updatedAt": "2026-05-20T10:00:00Z"
  },
  "usageInfo": {
    "creditsConsumed": 0.029016
  }
}

stringDocument — the rendered per-section output, keyed by section UUID. Always present.
structuredDocument — populated when one or more sections declare an outputSchema. Keyed the same way; each entry holds the schema-typed value (string, number, boolean, object, or array). A string leaf is a valid outputSchema, so string-typed sections show up here too — this field reflects whether a schema was declared, not whether the type is non-string.
templateVersionId — the exact template version used. Store it for reproducibility.

See the full response shape in the Guided Documents overview.

Next steps

Beginner's Guide

How facts, sections, templates, and schemas fit together — in plain language.

Guided Document Synthesis

The endpoint reference. Four template-supply paths, input context options, response shape.

Sections & Templates

Author your own sections and templates or inherit from Corti Standards.

Corti Standards library

Browse the curated catalogue to find a templateId to use in the doc-gen step.

Prompting Best-practices

Patterns for contentPrompt, writingStylePrompt, miscPrompt, and outputSchema descriptions.

Customization Guide

Inherit, override at runtime, or author your own — with per-customer and per-user patterns.

Please contact us if you run into issues with your first end-to-end request.

​Prerequisites

​Pick your scenario

Create an interaction

Capture and stream audio in real time

Generate a note from the interaction

Create an interaction

Upload the recording

Generate a transcript

Extract and store facts (optional)

Generate a note from the interaction

​What you get back

​Next steps

Beginner's Guide

Guided Document Synthesis

Sections & Templates

Corti Standards library

Prompting Best-practices

Customization Guide

Prerequisites

Pick your scenario

What you get back

Next steps