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

# Headless Web SDK Introduction

> A collection of React hooks and core functionality to build web applications on top of Suki ambient intelligence capabilities without pre-built UI components

The Suki Headless Web SDK is a React library that lets you add <Tooltip tip="Ambient documentation captures clinical conversations and generates notes automatically." cta="View in Glossary" href="/Glossary/a">ambient</Tooltip> documentation to your web application. You build the UI, while the SDK provides React hooks for authentication, session management, audio recording, and note generation.
Use the Headless Web SDK when you want complete control over the user interface and user experience. Unlike the [Web SDK](/web-sdk/overview), it does not include pre-built UI components.

After you initialize `PlatformClient` and wrap your application with `PlatformClientProvider`, use the provided React hooks, such as `useAuth`, `useAmbient`, and `useAmbientSession`, to authenticate users, manage sessions, and control recording.

## Supported platforms

The Headless Web SDK is currently supported on:

<CardGroup cols={1}>
  <Card title="React" icon="react">
    The SDK provides React hooks optimized for React applications. Requires React **18.0** or higher.

    Install the Headless Web SDK for React:

    <div className="install-btns-v2">
      <button className="install-btn-v2" data-cmd="npm install @suki-sdk/platform-react">
        <span className="install-btn-v2-label">Install for React</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>
</CardGroup>

## Headless Web SDK capabilities

The Headless Web SDK provides all the core capabilities of the Suki platform:

<CardGroup cols={3}>
  <Card title="Ambient Note Generation" icon="note">
    Capture clinical conversations and generate structured notes automatically
  </Card>

  <Card title="Real-Time Audio Streaming" icon="microphone">
    Receive real-time audio from the patient-provider conversation
  </Card>

  <Card title="Session Management" icon="clock">
    Full control over recording lifecycle (start, pause, resume, submit)
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Custom UI Integration" icon="paint-brush">
    Design your own recording interface, waveforms, and status indicators
  </Card>

  <Card title="React Hooks" icon="react">
    Simple, declarative API using React hooks for state management
  </Card>
</CardGroup>

### When to use the Headless Web SDK

Choose the Headless Web SDK when you want to:

* Build your own UI for Ambient workflows instead of using Suki's hosted experience.
* Integrate ambient recording capabilities into an existing web application.
* Customize the user experience to match your application's design system and workflows.
* Control how and when UI components are rendered.

<Note>
  If you prefer pre-built UI components and want to get started quickly, consider using the [Suki Web SDK](/web-sdk/overview) instead.
</Note>

## Common integration patterns and use cases

The Headless Web SDK gives you React hooks for authentication, ambient session management, audio capture, and recording controls. Your application owns the user interface, workflow, and how notes are retrieved or handed off after recording.

The following examples show common ways to integrate the Headless Web SDK into your React application.

<CardGroup cols={2}>
  <Card title="Build a Custom Ambient UI" icon="paint-brush">
    Use the authentication and ambient hooks to build your own recording controls, waveforms, session status, and other UI components that match your application's design.
  </Card>

  <Card title="Control the Recording Workflow" icon="clock">
    Use **`useAmbient`** and **`useAmbientSession`** to start, pause, resume, and submit ambient sessions from your own buttons, screens, and application workflow.
  </Card>

  <Card title="Support Multiple Clinical Workflows" icon="stethoscope">
    Reuse the same Headless hooks across different workflows, such as specialty clinics, nursing, or telehealth, while building separate React interfaces for each experience.
  </Card>

  <Card title="Retrieve Notes with Ambient APIs" icon="code">
    Capture audio with the Headless Web SDK, then retrieve generated notes and structured data from your backend using the Ambient APIs for EHR integration.
  </Card>

  <Card title="Embed Ambient Features into Existing Apps" icon="gauge-high">
    Add ambient session management and recording capabilities to an existing React application without embedding the headed Web SDK interface.
  </Card>

  <Card title="Build Custom Recording Experiences" icon="flask">
    Use the Headless hooks to prototype and build multi-step, guided, or other custom recording workflows without depending on the headed Web SDK UI.
  </Card>
</CardGroup>

## How the Headless Web SDK works

The following diagram illustrates the Headless Web SDK architecture and workflow:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    subgraph client["Your web application"]
        direction TB
        A["Application code<br/><small>React application</small>"]
        B["Headless Web SDK<br/><small>@suki-sdk/platform-react</small>"]
        C["Your own UI<br/><small>Your design • Recording controls • Status display</small>"]
        A --> B
        B --> C
    end
    
    subgraph platform["Suki backend"]
        direction TB
        D["Authentication service<br/>"]
        E["Ambient service<br/>"]
        F["AI engine<br/>"]
    end
    
    B -->|Authenticate| D
    C -->|Stream audio| E
    E -->|Process| F
    F -->|Return results| C
    
    style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827
    style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827
    style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style F fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
```

### Architecture workflow

<Steps>
  <Step title="Client Side (Your Web Application)" icon="user">
    * Your React application that integrates the Headless Web SDK.
    * React SDK package (`@suki-sdk/platform-react`) that provides React hooks for authentication, session management, and recording control.
    * Your custom UI components built using the hook state and methods for recording controls, status display, and visualization.
  </Step>

  <Step title="Suki Backend" icon="server">
    * **Authentication Service**: Validates user credentials and manages session tokens.
    * **ambient Service**: Handles audio streaming, session management, and real-time transcription.
    * **AI Engine**: Processes audio data and generates structured clinical notes.
  </Step>

  <Step title="Data Flow" icon="arrow-right">
    1. Create `PlatformClient`, wrap the app with `PlatformClientProvider`, then use `useAuth` with partner credentials -> Authenticate with Suki backend.
    2. Create ambient session using `useAmbient` hook -> Get `ambientSessionId`.
    3. Initialize `useAmbientSession` hook with the `ambientSessionId` -> Get recording controls.
    4. Build custom UI using hook state and methods.
    5. User starts recording using `start()` method -> SDK streams audio to ambient Service.
    6. AI Engine processes audio and generates notes.
    7. Results return through hooks -> Your custom UI displays the note and transcript.
  </Step>
</Steps>

## Next steps

Get started by following these steps:

<Icon icon="file-lines" iconType="solid" /> Refer to the [Installation guide](/headless-web-sdk/installation) to add the package to your project

<Icon icon="file-lines" iconType="solid" /> Refer to the [Quickstart](/headless-web-sdk/quickstart) for `PlatformClient` and `PlatformClientProvider`, then the [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) guide for `useAuth`

<Icon icon="file-lines" iconType="solid" /> Refer to the [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook) guide to create an ambient session

<Icon icon="file-lines" iconType="solid" /> Refer to the [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) guide to manage the ambient session