> ## 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.
# Ambient & Dictation APIs Overview
> Plan an Ambient or Dictation integration with REST session APIs, Partner WebSocket audio, webhooks, and endpoints for notes, preferences, feedback, and structured clinical output
**New**
The Ambient APIs are now interoperable with other Suki products that support Ambient workflows. Pass `emr_encounter_id` when you create an ambient session so clinicians can continue the same clinical note across Ambient APIs, Mobile SDK, and Web SDK.
Refer to [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) for more information.
**Are you a Suki partner?**
To use any Suki API or SDK, you must be a Suki partner. Contact the partnership team to begin the onboarding process. They help you set up your authentication system and get started with the Suki APIs and SDKs.
Suki Ambient APIs let you integrate **Ambient clinical documentation** into your application. You can create and manage **ambient sessions**, stream visit audio, and retrieve AI-generated **clinical notes** while maintaining full control over your application's workflows and user experience.
An encounter is the patient visit. An ambient session is one recording for that visit. One encounter can include one or more ambient sessions.
During an ambient session, providers and patients have a real-time conversation while Suki processes the streamed audio and generates a clinical note. Most operations use REST APIs and return standard [HTTP status codes](/api-reference/https-guidelines).
Audio is streamed over the Partner WebSocket (`GET /ws/stream`) using the ambient session ID. When note generation is complete, you can poll session status and retrieve content, or use a webhook so you do not need to poll continuously.
The same APIs also support **Dictation** when you need transcription without the full clinical note workflow. You create a Dictation session, stream audio, and retrieve the transcript in real time. To learn more, refer to [Audio Dictation](/documentation/concepts/dictation/dictation).
## Available APIs
The following set of APIs are available for the Ambient and Dictation workflows. Refer to each card below to learn more about the endpoints and how to use them.
Endpoints for authentication and authorization.
Endpoints for ambient session management.
Endpoints for Dictation.
Endpoints for content retrieval after the session is completed.
Endpoints for managing the user preferences.
Endpoints for managing user feedback.
Endpoints for managing notifications to your service.
Endpoints for retrieving information about the encounter type, visit type, and provider role.
Endpoints for retrieving information about the medication orders.
## Authentication
For an overview of Suki's supported authentication mechanisms refer to [Authentication mechanisms](/documentation/how-to/partner-authentication). We recommend using OAuth 2.0 with JWT tokens for your authentication system.
If you know what your authentication model is, refer to the following guides to get started:
All Suki API requests must include the following headers:
| Header | Value | Required |
| :-------------- | :----------------------------------- | :---------- |
| `Authorization` | `Bearer ` | Yes |
| `partner_token` | JWT issued by your identity provider | Yes |
| `Content-Type` | `application/json` | Yes |
| `Accept` | `application/json` | Recommended |
If you're using a Suki SDK, the SDK manages authentication and sends the required headers automatically after authentication is configured.
## Key capabilities
The Ambient APIs provide the following capabilities, so you can control audio capture, note quality, and how generated outputs reach your product and downstream systems.
Create ambient sessions, stream visit audio over the Partner WebSocket, and pause, resume, or end each session when that recording is finished.
Turn provider-patient conversations into structured clinical notes and full transcripts, then retrieve draft content and metadata after processing finishes.
Let patients speak in 80+ languages while Suki generates English notes and transcripts that fit standard EHR workflows.
Set provider-level verbosity and section formats through the User Preferences API so generated notes match how each clinician documents care.
Organize documentation by patient problems, merge existing diagnoses from context, and retrieve ICD10, IMO, SNOMED, and HCC structured output for EHR integration.
Convert medication instructions from ambient encounters into structured Medication order data for APIs, Mobile SDK, and Web SDK.
Extract diagnoses, medications, and other encounter-level artifacts from the conversation for charting, orders, and analytics in your application.
Configure which LOINC-based sections appear in generated notes so output aligns with your specialty templates and compliance requirements.
Run speech-to-text sessions when you need transcription without the full ambient clinical note workflow.
Receive webhook callbacks when processing completes, and submit feedback on transcripts or generated content to track quality over time.
## Requirements
Before you can use the Ambient and Dictation APIs, meet these requirements:
* You must be a Suki partner. Learn more about how to become a Suki partner in the [Partner onboarding](/documentation/get-started/partner-onboarding) documentation.
* A standards-based authentication system (for example OAuth 2.0 or OpenID Connect with JWTs).
* JWT tokens with consistent user identifiers (for example `sub`, `email`, or `userId`).
* A publicly accessible JWKS endpoint for token verification.
## Common integration patterns and use cases
The Ambient APIs provide REST and WebSocket endpoints to create ambient sessions, stream audio, complete sessions, and retrieve clinical outputs. Your application owns the capture UI, session orchestration, and how notes are reviewed or persisted.
The following examples show common ways to integrate the Ambient APIs into your application.
Create the session through REST, stream visit audio over the Partner WebSocket, and expose recording controls in your own interface.
End the session, receive a completion webhook or poll status, then retrieve the generated clinical note and related outputs when processing completes.
Map LOINC-based note sections, transcripts, and available structured data into your review and EHR persistence workflow after the session completes.
Use Dictation APIs when your application needs real-time transcription without running the ambient note-generation workflow.
## API versioning
All endpoints use the `/api/v1/` prefix. **v1** is the stable version. Non-breaking changes may ship without a major version jump. For policies and migration, refer to [API guidelines](/api-reference/api-guidelines#version-management).
These APIs may include Early Access features. If you are unsure what is enabled for your account, contact your Suki representative.
## Suki Ambient APIs workflow
To integrate with the Suki Ambient API, you follow a session-based workflow.
```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
Start([Start Session]) --> Auth[Authentication]
Auth --> Check{User registered?}
Check -->|No| Register[Register new user]
Register --> Auth
Check -->|Yes| Token[Get sdp_suki_token]
Token --> Create[Create session]
Create --> SessionID[Get ambient_session_id]
SessionID --> Context{Seed Context?}
Context -->|Yes| AddContext[Add additional context]
Context -->|No| Stream
AddContext --> Stream[Stream audio chunks]
Stream --> Control[PAUSE/RESUME/KEEP_ALIVE]
Control --> Done{Session Complete?}
Done -->|No| Stream
Done -->|Yes| End[Generate note]
End --> Wait[AI processing]
Wait --> Notify{Webhook configured?}
Notify -->|Yes| Hook[Receive notification]
Notify -->|No| Poll[Poll status]
Hook --> Retrieve
Poll --> Retrieve[Retrieve note]
Retrieve --> Complete([Session Complete])
classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
classDef registerStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000
classDef highlightStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000
class Auth,Create,Stream,End authStyle
class Register registerStyle
class Retrieve highlightStyle
```
### Developer workflow
Authenticate with Suki to get a Suki authentication token, also called `suki_token`.
Create an ambient session for the patient visit. One encounter can include more than one session.
Stream visit audio over WebSocket to the Suki backend.
End the ambient session when that recording is finished. Ending a session is not the same as closing the encounter.
Retrieve generated outputs through REST endpoints.
If webhooks are enabled for your partner account, your application will receive automatic completion notifications instead of relying only on polling.
**Best practices**
* Store **partner\_id**, **partner\_token**, and issued tokens securely; rotate credentials per your security policy.
* Send API traffic over HTTPS and validate webhook signatures when your integration receives callbacks.
* Read HTTP status and error bodies from REST responses; handle auth expiry by refreshing **suki\_token** as documented.
## Next steps
Refer to the [Ambient APIs quickstart](/api-reference/quickstart) to get started.