> ## 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
Suki provides **REST APIs** that let you add **Ambient Clinical Documentation workflows** to your application. The APIs give you full control over your application workflows and user experience while enabling you to capture visit conversations and generate clinical notes.
The Suki Ambient APIs support **ambient sessions** where providers and patients have real-time conversations. During a session, Suki processes encounter audio and produces **clinical notes** for your product to retrieve. Most operations use REST endpoints and return standard [HTTP status codes](/api-reference/https-guidelines).
Visit audio is streamed over the Partner WebSocket (`GET /ws/stream`) using your ambient session ID. Webhooks notify your application when processing is complete, which removes the need for continuous polling.
## Key capabilities
The Ambient APIs expose the capabilities below so you can control 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 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/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.
## What you can build
Use the Ambient APIs to build custom ambient clinical documentation workflows. Control how sessions are created, how audio is captured and streamed, and how notes and outputs are presented in your product.
You can configure note generation based on:
* Visit types
* Specialties
* Compliance requirements
* Existing clinical processes etc.
Implement your own logic for session state management, note review, editing, and downstream handoff workflows and connect to your EHR, telehealth platform, or internal systems using REST APIs, WebSockets, and optional webhooks.
### Common use cases
Create your own ambient session workflow with full control over the user experience, from session creation to note retrieval.
Build custom UI and workflow logic for pausing, resuming, and canceling ambient sessions within your application.
Integrate ambient session creation, audio streaming, and structured output retrieval directly into your EHR or telehealth platform.
## 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 APIs
The following set of 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.