> ## 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 APIs Overview
> Introduction to the Suki Ambient APIs: REST, Partner WebSocket audio, webhooks, sessions, clinical notes, 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 the platform overview.
Suki Ambient APIs let you integrate **Ambient clinical documentation** into your application. You can create and manage **ambient sessions**, stream encounter audio, and retrieve AI-generated **clinical notes** while maintaining full control over your application's workflows and user experience.
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, Suki sends a webhook notification to your application, so you don't need to continuously poll for results.
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).
## 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 encounter audio over the Partner WebSocket, and pause, resume, or end capture when the visit is complete.
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.
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 & Dictation APIs, you need to meet the following 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.
* HTTP/2.0 compliant authentication system (e.g. OAuth 2.0, JWT, etc.).
* JWT tokens with consistent user identifiers (e.g. `sub`, `email`, `userId`, etc.).
* 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 encounter 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.
## Available Partner APIs for Ambient and Dictation workflows
The following set of Partner APIs are available for the Ambient and Dictation workflows. View each card below to learn more about the endpoints that are available 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.
## 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 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 to start a new visit.
Stream visit audio over WebSocket to the Suki backend.
End the session when the visit is complete.
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.