---
name: Platform
description: Use when building healthcare applications that need ambient clinical documentation, form filling, dictation, or voice-powered workflows. Reach for this skill when integrating Suki's AI capabilities into EHRs, telehealth platforms, mobile apps, or custom healthcare systems.
metadata:
    mintlify-proj: platform
    version: "1.0"
---

# Suki for Partners

## Product summary

Suki for Partners is a developer platform providing ambient clinical documentation, form filling, dictation, and voice-powered workflows for healthcare applications. Agents use it to integrate AI-powered clinical note generation, speech-to-text, and structured form capture into web, mobile, and backend systems without building AI infrastructure.

**Key files and commands:**
- Authentication: Partner ID + JWT token (partner_token) from your identity provider
- Session creation: REST API `POST /api/v1/ambient/session/create` or SDK methods
- Audio streaming: WebSocket `wss://sdp.suki.ai/ws/stream` (production) or `wss://sdp.suki-stage.com/ws/stream` (staging)
- Content retrieval: REST API `GET /api/v1/ambient/session/{session_id}/content`
- SDKs: `@suki-sdk/js`, `@suki-sdk/react` (Web), Mobile SDK (iOS), Headless Web SDK (React 18+), Dictation SDK
- Primary docs: https://developer.suki.ai

## When to use

Reach for this skill when:
- Building or integrating into EHR systems, telehealth platforms, or care management tools
- Adding ambient clinical note generation from patient-provider conversations
- Implementing speech-to-text or dictation workflows in healthcare apps
- Creating form-filling workflows for nursing or clinical staff
- Integrating multilingual support (80+ languages) with English note generation
- Customizing note sections using LOINC codes for specialty-specific templates
- Handling session lifecycle (create, stream audio, retrieve structured output)
- Implementing authentication with JWT tokens and JWKS endpoints
- Troubleshooting audio streaming, session status, or content retrieval issues

## Quick reference

### Integration paths

| Path | Best for | What you build |
|------|----------|----------------|
| **Web SDK** | React/JS web apps | Pre-built UI components; minimal custom code |
| **Headless Web SDK** | React 18+ with custom UI | React hooks for auth, sessions, recording; you own layout |
| **Mobile SDK** | Native iOS apps | Native iOS integration; custom UI |
| **Ambient APIs** | Custom implementations, multi-platform | Complete REST/WebSocket control; maximum flexibility |
| **Dictation SDK** | Web apps needing speech-to-text | Hosted iframe for dictation; in-field or scratchpad modes |

### Authentication flow

1. User signs in to your app → your identity provider issues JWT (partner_token)
2. Initialize SDK/API with `partnerId` + `partnerToken`
3. Suki validates token using your JWKS endpoint
4. Suki returns `sdp_suki_token` (valid 1 hour)
5. Include `sdp_suki_token` header in all subsequent API calls

### Session lifecycle (APIs)

```
POST /api/v1/ambient/session/create
  → Returns ambient_session_id

POST /api/v1/ambient/session/{id}/context
  → Seed patient, provider, section info

WebSocket wss://sdp.suki.ai/ws/stream
  → Stream audio chunks (Base64 PCM, 16-bit, 16kHz)
  → End with AUDIO frame containing Base64 of "EOF"

POST /api/v1/ambient/session/{id}/end
  → Trigger note generation

GET /api/v1/ambient/session/{id}/content
  → Retrieve structured clinical note

GET /api/v1/ambient/session/{id}/transcript
  → Retrieve full conversation transcript
```

### LOINC codes (common sections)

| LOINC | Section |
|-------|---------|
| 10164-2 | History of Present Illness |
| 29545-1 | Physical Exam |
| 51847-2 | Assessment and Plan |
| 10154-3 | Chief Complaint |
| 10160-0 | Medications |
| 11348-0 | Past Medical History |
| 10187-3 | Review of Systems |
| 29762-2 | Social History |

See [documentation/note-sections](https://developer.suki.ai/documentation/note-sections) for complete list.

### Environment URLs

| Environment | REST | WebSocket |
|-------------|------|-----------|
| **Production** | `https://sdp.suki.ai` | `wss://sdp.suki.ai` |
| **Staging** | `https://sdp.suki-stage.com` | `wss://sdp.suki-stage.com` |

## Decision guidance

### When to use Web SDK vs Headless Web SDK vs APIs

| Your need | Choose | Why |
|-----------|--------|-----|
| **Fastest web integration** | Web SDK | Pre-built clinical UI; minimal setup |
| **Custom web UI in React** | Headless Web SDK | Hooks for platform behavior; you own all UI |
| **Custom UI without React** | Ambient APIs | Full control at REST/WebSocket level |
| **Multi-platform (web + mobile + backend)** | Ambient APIs | Single API surface across all clients |
| **Native iOS app** | Mobile SDK | Native device integration and performance |

### When to use form filling vs ambient documentation

| Use case | Choose |
|----------|--------|
| **Generate structured clinical notes from conversations** | Ambient documentation |
| **Collect structured data into predefined medical forms** | Form filling |
| **Transcribe speech without note generation** | Dictation |

## Workflow

### Typical ambient documentation task

1. **Understand the project**
   - Identify integration path (Web SDK, APIs, Mobile SDK, etc.)
   - Confirm partner ID and JWKS endpoint are registered with Suki
   - Determine target environment (staging or production)

2. **Check existing setup**
   - Verify JWT token generation in your identity provider
   - Confirm JWKS endpoint is publicly accessible
   - Test authentication flow with `/api/v1/auth/login` endpoint
   - Validate `sdp_suki_token` is returned and valid for 1 hour

3. **Create and configure session**
   - Call `POST /api/v1/ambient/session/create` with `ambient_session_id` and `encounter_id` (max 36 chars)
   - Call `POST /api/v1/ambient/session/{id}/context` to seed patient demographics, provider specialty, and LOINC section codes
   - Confirm session status is `created` (not `failed`)

4. **Stream audio**
   - Open WebSocket to `wss://sdp.suki.ai/ws/stream`
   - Send authentication headers: `sdp_suki_token` and `ambient_session_id`
   - Stream audio as Base64-encoded PCM chunks (100ms chunks recommended)
   - Send final AUDIO frame with Base64 of "EOF" (`RU9G`)
   - Close WebSocket

5. **End session and retrieve content**
   - Call `POST /api/v1/ambient/session/{id}/end` to trigger note generation
   - Poll `GET /api/v1/ambient/session/{id}/status` until status is `COMPLETED` (or use webhooks)
   - Call `GET /api/v1/ambient/session/{id}/content` to retrieve structured note
   - Call `GET /api/v1/ambient/session/{id}/transcript` to retrieve full transcript

6. **Verify and integrate**
   - Confirm note sections match your LOINC configuration
   - Validate structured data (diagnoses, medications) extracted correctly
   - Map note sections to your EHR's expected format
   - Test error handling for network failures, expired tokens, and short sessions

## Common gotchas

- **Session duration requirement**: Sessions must be **at least 1 minute long**. Shorter sessions receive `SKIPPED` status and no note is generated. This is not an error—it's expected behavior.

- **Token expiration**: `sdp_suki_token` is valid for **1 hour**. Refresh before expiry by calling `/api/v1/auth/login` again. Include the new token in all subsequent API calls.

- **WebSocket authentication**: Browser clients must send `Sec-WebSocket-Protocol` header as comma-separated: `SukiAmbientAuth,{ambient_session_id},{sdp_suki_token}`. Non-browser clients send `sdp_suki_token` and `ambient_session_id` as HTTP headers on the WebSocket upgrade request.

- **Audio format**: Stream PCM audio (16-bit, 16kHz mono). Base64-encode chunks before sending. End with AUDIO frame containing Base64 of "EOF" (value `RU9G`), then close WebSocket and call `/end` endpoint.

- **Session ID length**: `ambient_session_id` and `encounter_id` must be **at most 36 characters** (varchar(36)). Longer IDs cause session creation to fail silently.

- **Context before streaming**: Call `/context` endpoint **before** opening the WebSocket. Seeding context after streaming starts often causes failures or incomplete notes.

- **LOINC codes are required**: Specify at least one LOINC code in session context. Without sections, note generation may fail or return empty content.

- **Deprecated patterns**: Do not use `prefill.noteTypeIds` (Web SDK v1). Use LOINC codes instead. Migrate to v2+ for proper section configuration.

- **Multilingual notes**: Patients can speak in 80+ languages, but generated notes are always in English. Set `multilingual: true` in session creation.

- **Empty transcript or content**: If retrieval returns empty data, check: (1) session status is `COMPLETED` not `PROCESSING`, (2) session was at least 1 minute long, (3) audio contained actual speech (not silence), (4) you waited 5-10 seconds after `/end` before retrieving.

- **WebSocket connection drops**: Implement retry logic with exponential backoff. Check network connectivity and firewall rules. Ensure `sdp_suki_token` hasn't expired.

## Verification checklist

Before submitting work:

- [ ] Authentication works: `/api/v1/auth/login` returns valid `sdp_suki_token`
- [ ] Session creation works: `/session/create` returns `ambient_session_id` with status `created`
- [ ] Context seeded: `/session/{id}/context` call succeeds before WebSocket opens
- [ ] Audio streams: WebSocket connection established, audio chunks sent, EOF frame sent
- [ ] Session ends: `/session/{id}/end` called after audio stream closes
- [ ] Content retrieved: `/session/{id}/content` returns structured note with sections matching LOINC codes
- [ ] Transcript retrieved: `/session/{id}/transcript` returns full conversation text
- [ ] Session duration: Recording is at least 1 minute long (not `SKIPPED`)
- [ ] Error handling: Network failures, token expiry, and short sessions handled gracefully
- [ ] LOINC sections: Generated note sections match your configured LOINC codes
- [ ] Structured data: Diagnoses, medications, and other coded data extracted correctly

## Resources

**Comprehensive navigation:** https://developer.suki.ai/llms.txt

**Critical documentation pages:**
- [Getting Started / Quickstart](https://developer.suki.ai/documentation/getting-started) — Step-by-step integration for all paths
- [Partner Authentication](https://developer.suki.ai/documentation/partner-authentication) — JWT, JWKS, token validation
- [Ambient APIs Overview](https://developer.suki.ai/api-reference/overview) — REST endpoints, WebSocket, session lifecycle
- [Web SDK Overview](https://developer.suki.ai/web-sdk/overview) — Pre-built components and React integration
- [Note Sections (LOINC Codes)](https://developer.suki.ai/documentation/note-sections) — Complete list of supported sections
- [Integration Decision Guide](https://developer.suki.ai/documentation/integration-decision-guide) — Choose your path (APIs, Web SDK, Mobile SDK, Headless Web SDK)

---

> For additional documentation and navigation, see: https://developer.suki.ai/llms.txt