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

> 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 provides **React hooks** and **core functionality** that let you integrate <Tooltip tip="Ambient documentation captures clinical conversations and generates notes automatically." cta="View in Glossary" href="/Glossary/a">ambient</Tooltip> intelligence capabilities into your web application while maintaining complete control over your user interface.

Unlike the [Suki Web SDK](/web-sdk/overview), which includes pre-built UI components, the Headless Web SDK gives you the backend functionality and lets you design every aspect of the user experience. This approach gives you maximum flexibility to match your application's design system and user experience requirements.

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

## Key features

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 Headless Web SDK

Choose the Headless Web SDK when:

* You want to embed ambient intelligence into your existing web application with a custom UI
* You need complete control over the user interface and user experience
* You want to match your application's existing design system and branding
* You need to optimize performance by controlling what UI components are rendered
* You're building a custom workflow that requires specific UI interactions

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

## How it 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