Work with Multiple Recordings

• End an Ambient session
• Retrieve Ambient content
• Approve a note
• Save a note to an EHR

​

When to add listen-back or downloading capabilities to your application

• Review a section of the conversation when the generated note does not look right.
• Verify what was said without leaving the patient chart.
• Support an existing audit or compliance workflow that requires access to the source recording.
• Meet organizational requirements or service-level agreements that require access to recorded audio.

​

What your application needs to handle

• Listen-back controls: Add a listen or playback action button where clinicians review the note or visit. Keep this separate from the live recording experience.
• Recording URL retrieval: Retrieve the recording URL using the Get Ambient session recording API when the audio is available.
• Temporary URL handling: Presigned URLs expire after a short time. Each item in recordings includes expires_at so your application knows when the URL is no longer valid. When the URL expires or playback fails, call Get Ambient session recording again for a new URL. See URL validity and refresh for expiry times and refresh rules.
• Access control: Restrict access for downloading or listening to the recording according to your application’s authorization model and the user’s access level.

​

URL validity and refresh

​

Recommended flow for integration

• Call Get Ambient session recording API asynchronously when the clinician opens your listen-back or downloading capabilities action button or when your archive job runs, not long before, and cache the URL for later.
• Watch expires_at on each item in recordings. Request a new URL before it passes, or immediately when playback or download fails.
• When a presigned URL expires, call the recording endpoint again with the same ambient_session_id. Use the new presigned_url and the same download mode (stream or full file) you used before.
• On 404, wait and retry. The recording may still be processing (common for uploaded audio).
• On 410, stop retrying. The session is past the 7-day retention window.
• If is_streamable is false, call the endpoint again with download=true instead of using streaming mode.
• For multi-chunk sessions, refresh per chunk in recordings and use sequence_number to keep playback order.

​

Wrong behavior

• Do not save presigned URLs as permanent chart links, EHR fields, or shared URLs. They expire and will break for other users.
• Do not treat 404 the same as 410. 404 can be temporary; 410 means the recording is gone for good.
• Do not keep retrying the recording API after 410. No new URL will be issued for that session.
• Do not use streaming URLs when is_streamable is false. Request download=true instead.
• Do not block approve, sign, or chart save on a successful recording fetch. Audio listen-back is optional.
• Do not assume the presigned URL outlives the recording file. Even a fresh URL only works while the session is within the 7-day window.

​

What you need to decide before you build

​

Common use cases

​

How recordings fit the visit

​

Recommended UI patterns

​

Implement Recording API in your application

​

Response structure

​

Example code

const response = await fetch(
  `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/recording`,
  {
    headers: {
      sdp_suki_token: sdpSukiToken,
      sdp_provider_id: sdpProviderId,
    },
  }
);
if (!response.ok) {
  throw new Error(`Get recording failed: ${response.status}`);
}
const data = await response.json();
// data.recordings[].presigned_url, expires_at: use in your player
for (const rec of data.recordings ?? []) {
  console.log(rec.presigned_url, rec.expires_at);
}

import requests

response = requests.get(
    f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/recording",
    headers={
        "sdp_suki_token": sdp_suki_token,
        "sdp_provider_id": sdp_provider_id,
    },
)
response.raise_for_status()
data = response.json()
for rec in data.get("recordings", []):
    print(rec.get("presigned_url"), rec.get("expires_at"))

​

Best practices

​

FAQs

​

Next steps