API Reference Workflows

End-to-end Embedded API workflow examples that combine multiple methods into realistic integration flows.

Use this page when you want end-to-end examples that combine multiple Embedded API methods into a realistic integration flow.

These workflows complement the individual method reference pages. Use the method pages when you need payload details, validation rules, or return shapes for one specific method.

Initialize and start recording

In the examples below, api refers to your Embedded API instance.

• Web Component / vanilla: const api = document.querySelector("corti-embedded");
• React: const api = useCortiEmbeddedApi(cortiRef);

navigate({ path: ... }) is used for cross-surface consistency.

• On @corti/embedded-web versions earlier than 0.3.0, use navigate("/session/...").
• On @corti/embedded-web@0.3.0 and later, both shapes are accepted.

try {
  // 1. Authenticate
  const user = await api.auth({
    access_token: "...",
    refresh_token: "...",
    id_token: "...",
    token_type: "Bearer",
  });
  console.log("Authenticated as:", user.email);

  // 2. Configure app-level settings (optional)
  await api.configureApp({
    locale: { dictationLanguage: "en" },
  });

  // 3. Configure interaction defaults (optional)
  await api.setInteractionOptions({
    mode: {
      fallback: "virtual",
      options: ["in-person", "virtual"],
    },
  });

  // 4. Create interaction
  const interaction = await api.createInteraction({
    encounter: {
      identifier: "enc-123",
      status: "planned",
      type: "ambulatory",
      period: { startedAt: new Date().toISOString() },
      title: "Patient Visit",
    },
  });

  // 5. Navigate to the session
  await api.navigate({ path: `/session/${interaction.id}` });

  // 6. Start recording
  await api.startRecording();
} catch (error) {
  console.error("Workflow failed:", error.message, error.code);
}

Handle recording startup errors

async function startRecordingWithRetry() {
  try {
    await api.startRecording();
  } catch (error) {
    switch (error.code) {
      case "UNAUTHORIZED":
        await reauthenticate();
        await api.startRecording();
        break;

      case "NOT_READY":
        if (error.message.includes("createInteraction")) {
          await api.createInteraction({
            encounter: {
              identifier: `enc-${Date.now()}`,
              status: "planned",
              type: "ambulatory",
              period: { startedAt: new Date().toISOString() },
            },
          });
          await api.startRecording();
        }
        break;

      default:
        console.error("Unexpected error:", error);
    }
  }
}

Complete session lifecycle

let currentInteractionId = null;

async function initializeSession() {
  await api.auth({
    /* tokens */
  });

  await api.configureApp({
    ui: {
      aiChat: true,
    },
  });

  await api.setInteractionOptions({
    mode: {
      fallback: "virtual",
      options: ["in-person", "virtual"],
    },
    spokenLanguage: {
      fallback: "en-US",
    },
  });
}

async function startNewInteraction(encounterData) {
  const interaction = await api.createInteraction({
    encounter: encounterData,
  });
  currentInteractionId = interaction.id;

  await api.addFacts([
    { text: "Chief complaint: Headache", group: "symptoms" },
  ]);

  await api.navigate({ path: `/session/${interaction.id}` });
  await api.startRecording();
  return interaction;
}

async function endInteraction() {
  await api.stopRecording();
  const status = await api.getStatus();
  return status.interaction;
}

Related reference

• API Reference Overview
• auth()
• createInteraction()
• startRecording()
• setInteractionOptions()