> ## 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.

# 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.

<Info>
  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.
</Info>

## Initialize and start recording

<Note>
  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.
</Note>

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/assistant/api-reference)
* [auth()](/assistant/api/auth)
* [createInteraction()](/assistant/api/create-interaction)
* [startRecording()](/assistant/api/start-recording)
* [setInteractionOptions()](/assistant/api/set-interaction-options)