Skip to main content
The Suki Headless Web SDK is a React library that lets you add 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, 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:

React

The SDK provides React hooks optimized for React applications. Requires React 18.0 or higher.Install the Headless Web SDK for React:

​
Headless Web SDK capabilities

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

Ambient Note Generation

Capture clinical conversations and generate structured notes automatically

Real-Time Audio Streaming

Receive real-time audio from the patient-provider conversation

Session Management

Full control over recording lifecycle (start, pause, resume, submit)

Custom UI Integration

Design your own recording interface, waveforms, and status indicators

React Hooks

Simple, declarative API using React hooks for state management

​
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.
If you prefer pre-built UI components and want to get started quickly, consider using the Suki Web SDK instead.

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

Build a Custom Ambient UI

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.

Control the Recording Workflow

Use useAmbient and useAmbientSession to start, pause, resume, and submit ambient sessions from your own buttons, screens, and application workflow.

Support Multiple Clinical Workflows

Reuse the same Headless hooks across different workflows, such as specialty clinics, nursing, or telehealth, while building separate React interfaces for each experience.

Retrieve Notes with Ambient APIs

Capture audio with the Headless Web SDK, then retrieve generated notes and structured data from your backend using the Ambient APIs for EHR integration.

Embed Ambient Features into Existing Apps

Add ambient session management and recording capabilities to an existing React application without embedding the headed Web SDK interface.

Build Custom Recording Experiences

Use the Headless hooks to prototype and build multi-step, guided, or other custom recording workflows without depending on the headed Web SDK UI.

​
How the Headless Web SDK works

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

​
Architecture workflow

Client Side (Your Web Application)

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

Suki Backend

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

Data Flow

  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.

​
Next steps

Get started by following these steps: Refer to the Installation guide to add the package to your project Refer to the Quickstart for PlatformClient and PlatformClientProvider, then the Authentication hook guide for useAuth Refer to the Create ambient session guide to create an ambient session Refer to the Manage ambient session guide to manage the ambient session
Last modified on August 13, 2026