ChartHero Developer Docs
Request accessAPI ReferenceOpenAPI JSON
Get Started

Core Concepts

AuthenticationEnvironmentsScopesPagination

Guides

Fetch encountersFetch documentsFetch transcript and audioReceive webhooksVerify webhook signatures
API ReferenceWebhooksErrorsChangelog

Guide

Fetch transcript and audio

Fetch finalized transcript turns and request short-lived audio URLs.

When to use this

Use GET /external/v1/encounters/{encounter_id}/documents/{document_id}/transcript for finalized transcript turns from an ambient transcript document.

Use GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio to request a short-lived URL for recording-backed audio when audio is available for that ambient transcript document.

Required scopes

Route Required scopes
GET /external/v1/encounters/{encounter_id}/documents/{document_id}/transcript encounters:read, documents:read
GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio encounters:read, documents:read, recordings:read

Transcript access is document-scoped. Audio URL access requires document route access plus the additional recordings:read scope.

Request

Fetch finalized transcript turns:

cURL
curl "https://api.example.test/external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_transcript_001/transcript" \
  -H "Authorization: Bearer <api_key>"

Request a short-lived audio URL:

cURL
curl "https://api.example.test/external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_transcript_001/audio" \
  -H "Authorization: Bearer <api_key>"

Neither route accepts query parameters.

Response

Transcript response:

JSON
{
  "encounter_id": "enc_synthetic_001",
  "document_id": "doc_synthetic_transcript_001",
  "transcript": {
    "provider": "deepgram",
    "audio_duration_seconds": 842.4,
    "turns": [
      {
        "speaker": "clinician",
        "start": 0.0,
        "end": 1.6,
        "text": "Synthetic clinician sample."
      },
      {
        "speaker": "patient",
        "start": 1.8,
        "end": 3.1,
        "text": "Synthetic patient sample."
      }
    ]
  }
}

Audio URL response:

JSON
{
  "audio_url": "https://media.charthero.example/signed-recording.wav?token=example",
  "expires_at": "2026-05-25T15:15:00Z"
}

Audio URLs are temporary access artifacts. Do not store signed URLs as durable identifiers, put them in client-visible logs, or use them after expiration.

Common errors

HTTP status Reason code What it means
400 unsupported_filter The request includes a query parameter that this route does not support.
400 unsupported_document_type The selected document is not an ambient transcript document supported by this route.
400 audio_not_available_for_document Audio is not available for the selected document.
401 missing_bearer, api_keys_disabled, test_prefix_not_allowed, malformed_token, invalid_key, disabled_key, revoked_key, or expired_key API-key authentication failed. Branch on the exact reason_code.
403 org_scope_only_required Organization-scoped API keys are required.
403 missing_scope The API key is missing encounters:read, documents:read, or recordings:read for audio.
403 route_not_allowed or organization_not_allowlisted The route is not enabled for the caller organization.
403 cross_organization_denied or demo_training_denied The encounter is not available to this API key.
404 encounter_not_found, document_not_found, transcript_not_found, or audio_not_found The requested resource is not available to the caller organization.
503 digest_key_unavailable or audio_storage_unavailable API-key verification or audio storage is temporarily unavailable.

Next steps

Receive webhooks

Use notifications before fetching transcript resources.

Review errors

Handle transcript, audio, and availability failures.