> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tortus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every method, option, and event in the TORTUS Embed SDK.

The complete public surface of `@tortus-ai/embed-client`. For task-oriented walkthroughs, see the [guides](/guides/consultations).

## loadTortus(config)

Initialises the TORTUS client and displays the standby screen automatically.

| Parameter            | Type                                     | Required | Description                                                                 |
| -------------------- | ---------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `publishableKey`     | `string`                                 | Yes      | Your TORTUS publishable API key.                                            |
| `container`          | `string \| HTMLElement`                  | Yes      | DOM selector or element for the iframe.                                     |
| `environment`        | `'production' \| 'sandbox'`              | Yes      | Which environment to connect to. Must be specified explicitly.              |
| `fetchClientSecrets` | `() => Promise<{ launchToken: string }>` | Yes      | Async function that returns secure credentials so the app can authenticate. |
| `integration`        | `Integration`                            | No       | Default EHR integration, inherited by consultations without their own.      |

**Returns** `Promise<TortusClient>`

See [Configuration](/configuration) for the full option list.

## client.display(screen)

Navigate to a specific screen.

| Parameter | Type                  | Required | Description            |
| --------- | --------------------- | -------- | ---------------------- |
| `screen`  | `'home' \| 'standby'` | Yes      | The screen to display. |

**Returns** `Promise<void>`: resolves when navigation completes, rejects if it isn't possible.

## client.consultations.start(consultation, options?)

Start a new consultation.

| Parameter      | Type     | Required | Description                                                          |
| -------------- | -------- | -------- | -------------------------------------------------------------------- |
| `consultation` | `object` | Yes      | Configuration including `mode`, patient data, and encounter details. |
| `options`      | `object` | No       | Behaviour options (see below).                                       |

**`options`**

| Option     | Type                  | Required | Description                        |
| ---------- | --------------------- | -------- | ---------------------------------- |
| `returnTo` | `'home' \| 'standby'` | No       | Screen to return to when complete. |

**Returns** `Promise<TortusConsultation>`

<Note>
  The `TortusConsultation` object contains all consultation data: `reference`, `mode`, `patient`,
  `customFields`, `metadata`, and `integration`. When the consultation completes, this same data is
  available in the `consultation` parameter of the `consultation:completed` event. The `result`
  parameter contains only the generated artifacts.
</Note>

## client.dictations.start(options?)

Start a new dictation session.

**`options`**

| Option     | Type                  | Required | Description                        |
| ---------- | --------------------- | -------- | ---------------------------------- |
| `returnTo` | `'home' \| 'standby'` | No       | Screen to return to when complete. |

**Returns** `Promise<TortusDictation>`

## client.meetings.start(meeting, options?)

Start a new meeting recording. See [Meetings](/guides/meetings) for full examples.

**`meeting`**

| Field       | Type                               | Required                      | Description                                         |
| ----------- | ---------------------------------- | ----------------------------- | --------------------------------------------------- |
| `mode`      | `'LIVE_RECORDING' \| 'AUDIO_FILE'` | Yes                           | How the meeting audio is captured.                  |
| `reference` | `string`                           | No                            | Cross-system identifier; auto-generated if omitted. |
| `title`     | `string`                           | No                            | Meeting title.                                      |
| `notes`     | `string`                           | No                            | Notes, such as an agenda captured live.             |
| `audio`     | `{ url: string }`                  | When `mode` is `'AUDIO_FILE'` | Audio source for pre-recorded meetings.             |

**`options`**

| Option     | Type                  | Required | Description                                  |
| ---------- | --------------------- | -------- | -------------------------------------------- |
| `returnTo` | `'home' \| 'standby'` | No       | Screen to return to when the meeting closes. |

**Returns** `Promise<TortusMeeting>`

The returned `TortusMeeting` exposes `setNotes?(notes)`, `setAudio?(audio)`, and `close()` for mid-flight updates and teardown.

## client.on(event, callback)

Subscribe to client events. See [Handling events & results](/guides/events-and-results) for payload details.

| Parameter  | Type       | Required | Description                           |
| ---------- | ---------- | -------- | ------------------------------------- |
| `event`    | `string`   | Yes      | The event name to subscribe to.       |
| `callback` | `function` | Yes      | Handler invoked when the event fires. |

**Consultation events**

| Event                    | When it fires                                                          |
| ------------------------ | ---------------------------------------------------------------------- |
| `consultation:started`   | A consultation has started.                                            |
| `consultation:resumed`   | An in-progress consultation was re-opened (e.g. after client restart). |
| `consultation:completed` | A consultation completed successfully.                                 |
| `consultation:error`     | A consultation failed with an error.                                   |
| `consultation:cancelled` | A consultation was cancelled.                                          |
| `consultation:closed`    | A consultation was closed.                                             |

**Meeting events**

| Event               | When it fires                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `meeting:started`   | A meeting has started.                                                                     |
| `meeting:resumed`   | An in-progress meeting was re-opened.                                                      |
| `meeting:updated`   | Meeting metadata (notes/audio) was updated.                                                |
| `meeting:completed` | A meeting completed successfully (suppressed when `disableFinishMeetingButton` is `true`). |
| `meeting:cancelled` | A meeting was cancelled.                                                                   |
| `meeting:closed`    | A meeting was closed.                                                                      |

**Event data**

For completion events, the `consultation` (or `meeting`) parameter contains all metadata, while `result` contains the generated artifacts (`medicalNotes`, `letters`, `medicalCodes`, `transcriptions`). Filter artifacts by `contentType` rather than relying on array order.

**Returns** a function that unsubscribes from the event.

## client.destroy()

Destroys the client and cleans up all resources.

**Returns** `Promise<void>`

<Note>
  `destroy()` cleans up all resources but won't remove historical data saved in the browser.
</Note>