> ## 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. # Work with Shared Notes > Choose session, note, or encounter Ambient content APIs when a visit has more than one recording, headed-product edits, or an EMR-keyed chart
Use session content for one recording. Use note-level APIs with composition\_id as note\_id when the shared note may include more recordings or Web SDK edits. Use list encounter notes with emr\_encounter\_id when the chart opens on the EHR visit. Encounter content uses Ambient encounter\_id, not emr\_encounter\_id.
[Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content) covers the simplest workflow: the clinician starts and stops one ambient session. Your application waits for the session to complete, then retrieves the generated note. Real workflows can be more complex. A visit may have: * More than one ambient session. * A note that was edited in a headed product such as Web SDK. * A note that your application needs to find using an EMR encounter. In these cases, retrieve the note based on what your screen represents. The identifier you use depends on that scope. Each retrieve API uses **one** of these identifiers. Do not mix `ambient_session_id`, `note_id`, Ambient `encounter_id`, and `emr_encounter_id` on the same request. ## Choose the scope that matches your screen | If your screen represents | Retrieve by | | :-------------------------------------- | :---------------------------- | | One ambient recording | `ambient_session_id` | | One generated note | `composition_id` as `note_id` | | All notes for an EMR encounter | `emr_encounter_id` | | Related re-ambient sessions on one note | Ambient `encounter_id` | This lets your application show the note that belongs to the workflow the clinician is viewing. For example, if the clinician opens a chart by EMR encounter, call list encounter notes with that `emr_encounter_id`, then load the selected note with note-level APIs. Do not retrieve only one ambient session when the screen represents the full EMR visit. Using the correct scope also helps your application: * Show the latest shared note when recording continues on another device. * Show edits that were already made in Web SDK. * Find all notes associated with an EMR encounter when the workflow includes multiple notes. ## What your application needs to track Store the identifiers needed for the workflows your application supports: * `ambient_session_id` for an individual ambient session. * `composition_id`, used as `note_id`, for a generated note. * `emr_encounter_id` when the note is associated with an EMR encounter. * Ambient `encounter_id` when your workflow groups re-ambient sessions on the same note. For note rendering, map note sections using `loinc_code` at the scope supported by the API you are calling. See [Note sections](/documentation/concepts/ambient-clinical-notes/note-sections). **Scope rules (agents):** * One recording on one client: [session content](/api-reference/ambient-content/content) and [session structured data](/api-reference/ambient-content/structured-data) with `ambient_session_id`. Wait until that session is `completed`. * Shared note, multiple ambient sessions, or headed-product edits: note-level APIs. Pass create `composition_id` as `note_id`. * Prefer [note content](/api-reference/ambient-content/note-content) when clinicians edited sections in a headed product such as Web SDK. That response returns accumulated sessions plus the latest edited section content. Session content does not include those headed edits. * List notes for an EMR visit: [List encounter notes](/api-reference/ambient-content/list-encounter-notes) with the same `emr_encounter_id` you sent on create. Use each returned note `id` as `note_id`. The list can include finished and unfinished notes. * Chart keyed by ambient encounter: [encounter content](/api-reference/ambient-content/encounter-content) and [encounter structured data](/api-reference/ambient-content/encounter-structured-data) with Ambient `encounter_id` (re-ambient grouping), not `emr_encounter_id`. * Cross-modality workflows require `emr_encounter_id` on create. Without it, notes are not interoperable across modalities. * Map sections with `loinc_code` at every scope. Session content omits empty requested sections. Encounter content still lists them, including an empty body. * Do not mix session and note IDs on the same request. If your screen represents one generated note, retrieve it with `composition_id` as `note_id`. See [Fetch note content with composition\_id](/documentation/cookbooks/get-note-content-by-composition-id) for a request example. Use this page when you still need to choose among `ambient_session_id`, `note_id`, `emr_encounter_id`, and Ambient `encounter_id`. ## Decide which content to load Pick the API that matches the screen the clinician is opening. Do not mix session and note IDs on the same request. **What you get:** * Note sections for **one** ambient recording * Session structured data for diagnoses and orders from that recording **When to call:** * Call after that session status is `completed`. * Use this path right after a single Start/Stop on this client. * Use this path when the clinician is reviewing only the recording they just ended. **What you get:** * Accumulated section content across every ambient session on the shared note * The **latest edited** section text after clinicians review or edit in Web SDK **When to call:** * Pass `composition_id` from create as `note_id`. * Use this path when the note spans more than one recording. * Use this path after headed-product review, before you write the note back to the EHR. **What you get:** * Every note tied to the EMR visit, including finished and unfinished notes * Each note `id` to pass as `note_id` on note-level APIs **When to call:** * Pass the same `emr_encounter_id` you sent on create. * Use this path when the chart opens on the EHR visit and must list notes. * Cross-modality notes require `emr_encounter_id` on create. Without it, notes are not interoperable across modalities. **What you get:** * Cumulative content and structured data for the ambient encounter grouping * Empty requested sections included, even when the body is blank **When to call:** * Pass Ambient `encounter_id` from create (the re-ambient grouping ID). * Use this path when your product loads cumulative content by ambient encounter. * Do **not** pass `emr_encounter_id` here. That ID belongs to list encounter notes. ## How the identifiers relate Create returns `ambient_session_id` and `composition_id`. Your application provides `emr_encounter_id` and Ambient `encounter_id` on create when you use them, then stores those values with the visit. Pass the ID that matches each retrieve API. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%% flowchart TD A[Create ambient session] --> B[Returns ambient_session_id] A --> C[Returns composition_id as note_id] P[You provide on create] --> D[emr_encounter_id when interoperable] P --> H[encounter_id for re-ambient] B --> E[Session content and structured data] C --> F[Note content, context, structured data] D --> G[List encounter notes] H --> I[Encounter content and structured data] style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style P fill:#FFFADE,stroke:#FFE148,stroke-width:2px,color:#111827 style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 style I fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827 ``` | Identifier | What it identifies | Pass it to | | :--------------------------- | :-------------------------------------------------- | :----------------------------------------------------------- | | `ambient_session_id` | One recording | Session content, session structured data, status, transcript | | `composition_id` / `note_id` | The shared clinical note | Note content, note context, note structured data | | `emr_encounter_id` | The EHR visit. One visit can contain multiple notes | Create (for interoperability) and list encounter notes | | Ambient `encounter_id` | Re-ambient grouping for one note | Create (reuse on later sessions) and encounter content | For field rules and product naming, see [Interoperable identifiers](/documentation/concepts/ambient-clinical-notes/interoperable-identifiers). Do not pass `emr_encounter_id` to encounter content or encounter structured data. Those endpoints use Ambient `encounter_id`. [List encounter notes](/api-reference/ambient-content/list-encounter-notes) is the EMR-keyed list API. Cross-modality workflows require `emr_encounter_id` on create. Without it, Suki still creates an ambient session, but the note is not interoperable across modalities. See [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability). ## Typical workflow for retrieving note and encounter content Keep `ambient_session_id` and `composition_id` from [Create an ambient clinical note](/documentation/how-to/ambient-clinical-notes/create-ambient-session). Store `emr_encounter_id` and re-ambient `encounter_id` when you use them. Do not ask the clinician to enter these identifiers. For the recording you just ended, poll [session status](/documentation/how-to/ambient-clinical-notes/handle-ambient-session-status) until it is `completed` before you call session content. List encounter notes can still return unfinished notes. Do not treat those as finished chart text. Single recording on this client: session content. Shared note or Web SDK edits: note content with `note_id`. Chart opens by EMR visit: list encounter notes, then note-level APIs. Chart keyed by an ambient encounter: encounter content. Render note sections with `loinc_code` as the join key. Show your EHR titles in the UI. Hide sections omitted from session content. For encounter content, empty bodies can still appear. Do not invent note text. See [Note sections](/documentation/concepts/ambient-clinical-notes/note-sections). ## When to use each API **Scope accordions (agents):** Humans expand one panel at a time. * **One Ambient Recording Only:** Session content and session structured data. * **Shared Note across Sessions:** Note content, note context, note structured data with `composition_id` as `note_id`. * **After Clinicians Edit in Web SDK:** Note content for latest edited sections. * **List Notes for an EMR Encounter:** List encounter notes with `emr_encounter_id`. * **Chart Keyed by Ambient Encounter ID:** Encounter content and encounter structured data with Ambient `encounter_id`. Use [session content](/api-reference/ambient-content/content) and [session structured data](/api-reference/ambient-content/structured-data) with `ambient_session_id`. This is the default after a single Start/Stop on one client, right after that recording completes. Empty requested sections are omitted. Hide them in the UI. For the full note-review UI after End, see [Get the generated clinical note](/documentation/how-to/ambient-clinical-notes/retrieve-ambient-content). Use [note content](/api-reference/ambient-content/note-content), [note context](/api-reference/ambient-content/note-context), and [note structured data](/api-reference/ambient-content/note-structured-data). Pass `composition_id` from create as `note_id`. Note content accumulates every ambient session on that note. Use this when capture continues later in the same visit, or when Mobile SDK, Ambient APIs, and Web SDK share the note. See [Use interoperable ambient notes across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities). Prefer [note content](/api-reference/ambient-content/note-content) when clinicians reviewed or edited the note in a headed product such as Web SDK. For edited sections, the response returns the **latest edited** section content. Session content is only for one ambient session. After headed review, use note content so your EHR write-back is not missing those edits. See [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability). Use [List encounter notes](/api-reference/ambient-content/list-encounter-notes) with the same `emr_encounter_id` you sent on create. The list can include finished and unfinished notes. Use each returned note `id` as `note_id` for note-level calls. One EMR encounter can contain multiple clinical notes. Use [encounter content](/api-reference/ambient-content/encounter-content) and [encounter structured data](/api-reference/ambient-content/encounter-structured-data) when your product loads cumulative content by Ambient `encounter_id` (the re-ambient grouping ID you sent on create). This is not `emr_encounter_id`. Encounter content can include empty sections from the composition. Session content omits them. ## How to choose the right API You usecase determines the API you use and based on the API you use, you pass the corresponding ID. For example, if you are retrieving the note content for a shared note, you would pass the `composition_id` as `note_id`. | Goal | API | ID you pass | | :------------------------------------------------------ | :------------------------------------------------------------------------------------ | :--------------------------- | | Note sections for one recording | [Session content](/api-reference/ambient-content/content) | `ambient_session_id` | | Latest shared note text, including headed-product edits | [Note content](/api-reference/ambient-content/note-content) | `note_id` = `composition_id` | | Aggregated context for the shared note | [Note context](/api-reference/ambient-content/note-context) | `note_id` = `composition_id` | | Cumulative structured data for the shared note | [Note structured data](/api-reference/ambient-content/note-structured-data) | `note_id` = `composition_id` | | All notes on an EMR encounter | [List encounter notes](/api-reference/ambient-content/list-encounter-notes) | `emr_encounter_id` | | Cumulative content by Ambient encounter | [Encounter content](/api-reference/ambient-content/encounter-content) | Ambient `encounter_id` | | Cumulative structured data by Ambient encounter | [Encounter structured data](/api-reference/ambient-content/encounter-structured-data) | Ambient `encounter_id` | ## When to use note content after Web SDK edits Use [Get note content](/api-reference/ambient-content/note-content) when your application must stay in sync with a note clinicians already opened in the headed Web SDK (or another headed product). * Session content returns one ambient session. It is the default after a single Start/Stop on your client. * Note content returns accumulated section content across ambient sessions on that note. If clinicians edited sections in Web SDK, the response includes the **latest edited** section content. * Pass `composition_id` from [Create an ambient clinical note](/documentation/how-to/ambient-clinical-notes/create-ambient-session) as `note_id`. | Your screen | Prefer | | :------------------------------------------------------ | :-------------------------------------- | | Review this recording you just ended on this client | Session content | | Open the shared note after Web SDK review or edit | Note content | | Diagnoses and orders across every recording on the note | Note structured data | | Chart opens on an EMR visit and must list notes | List encounter notes, then note content | If capture started on Ambient APIs or Mobile SDK and the clinician edited in Web SDK, read the note back with note content. Do not assume session content includes those headed edits. ## Example code for loading latest note content by composition\_id
Get Note Content API List Encounter Notes API
**Language tabs (agents):** Equivalent code samples are available in: TypeScript, Python. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs. ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} const noteId = compositionId; // from Create ambient session const response = await fetch( `https://sdp.suki.ai/api/v1/ambient/note/${noteId}/content`, { headers: { sdp_suki_token: sdpSukiToken, sdp_provider_id: sdpProviderId, }, } ); if (!response.ok) { throw new Error(`Get note content failed: ${response.status}`); } const note = await response.json(); const sections = note.summary ?? []; for (const section of sections) { renderSection(section.loinc_code, section.title, section.content); } ``` ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import requests note_id = composition_id # from Create ambient session response = requests.get( f"https://sdp.suki.ai/api/v1/ambient/note/{note_id}/content", headers={ "sdp_suki_token": sdp_suki_token, "sdp_provider_id": sdp_provider_id, }, ) response.raise_for_status() note = response.json() for section in note.get("summary", []): render_section( section.get("loinc_code"), section.get("title"), section.get("content"), ) ``` Note content uses `summary[]` with `loinc_code`, `title`, and `content`, the same join key as session content. Map sections into your chart template by `loinc_code`. ## Available cookbooks