{ "components": { "schemas": { "PublicAmbientTranscriptDocumentDetail": { "additionalProperties": false, "description": "Ambient transcript document detail metadata without transcript turns.", "properties": { "audio_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Audio duration in seconds when known.", "title": "Audio Duration Seconds" }, "created_at": { "description": "Document creation timestamp.", "format": "date-time", "title": "Created At", "type": "string" }, "document_id": { "description": "Opaque public document identifier.", "title": "Document Id", "type": "string" }, "encounter_id": { "description": "Opaque public encounter identifier.", "title": "Encounter Id", "type": "string" }, "schema_type": { "const": "ambient_transcript", "description": "Discriminator for ambient transcript metadata responses.", "title": "Schema Type", "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ambient transcript lifecycle status when available.", "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document title when available.", "title": "Title" }, "updated_at": { "description": "Document last-update timestamp.", "format": "date-time", "title": "Updated At", "type": "string" }, "workflow_variant": { "anyOf": [ { "enum": [ "ambient", "phone_call" ], "type": "string" }, { "type": "null" } ], "description": "Ambient workflow variant when available.", "title": "Workflow Variant" } }, "required": [ "document_id", "encounter_id", "schema_type", "created_at", "updated_at" ], "title": "PublicAmbientTranscriptDocumentDetail", "type": "object" }, "PublicApiErrorResponse": { "additionalProperties": false, "properties": { "error": { "description": "Stable public error category.", "type": "string" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sanitized query field when applicable." }, "message": { "description": "Human-readable public error summary.", "type": "string" }, "reason_code": { "description": "Stable public reason code.", "enum": [ "api_keys_disabled", "audio_not_available_for_document", "audio_not_found", "audio_storage_unavailable", "cross_organization_denied", "demo_training_denied", "digest_key_unavailable", "disabled_key", "document_not_found", "encounter_not_found", "expired_key", "invalid_key", "invalid_limit", "invalid_offset", "invalid_query", "invalid_sort", "malformed_token", "missing_bearer", "missing_scope", "org_scope_only_required", "organization_not_allowlisted", "revoked_key", "route_not_allowed", "test_prefix_not_allowed", "transcript_not_found", "unsupported_document_type", "unsupported_filter" ], "type": "string" } }, "required": [ "error", "reason_code", "message", "field" ], "title": "PublicApiErrorResponse", "type": "object" }, "PublicClinicalDocumentDetail": { "additionalProperties": false, "description": "Clinical document detail with public markdown content.", "properties": { "content": { "$ref": "#/components/schemas/PublicDocumentMarkdownContent", "description": "Clinical document content." }, "created_at": { "description": "Document creation timestamp.", "format": "date-time", "title": "Created At", "type": "string" }, "document_id": { "description": "Opaque public document identifier.", "title": "Document Id", "type": "string" }, "encounter_id": { "description": "Opaque public encounter identifier.", "title": "Encounter Id", "type": "string" }, "schema_type": { "const": "document", "description": "Discriminator for clinical document detail responses.", "title": "Schema Type", "type": "string" }, "status": { "description": "Clinical document status is not exposed on this detail variant.", "title": "Status", "type": "null" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document title when available.", "title": "Title" }, "updated_at": { "description": "Document last-update timestamp.", "format": "date-time", "title": "Updated At", "type": "string" }, "workflow_variant": { "description": "Workflow variant is not exposed on clinical document detail responses.", "title": "Workflow Variant", "type": "null" } }, "required": [ "document_id", "encounter_id", "schema_type", "content", "created_at", "updated_at" ], "title": "PublicClinicalDocumentDetail", "type": "object" }, "PublicDocumentAudioResponse": { "additionalProperties": false, "description": "Public document audio URL response.", "properties": { "audio_url": { "description": "Short-lived signed URL for document audio.", "title": "Audio Url", "type": "string" }, "expires_at": { "description": "Timestamp when audio_url expires.", "format": "date-time", "title": "Expires At", "type": "string" } }, "required": [ "audio_url", "expires_at" ], "title": "PublicDocumentAudioResponse", "type": "object" }, "PublicDocumentDetailResponse": { "additionalProperties": false, "description": "Public document detail response.", "properties": { "document": { "description": "Supported public document detail.", "discriminator": { "mapping": { "ambient_transcript": "#/components/schemas/PublicAmbientTranscriptDocumentDetail", "document": "#/components/schemas/PublicClinicalDocumentDetail" }, "propertyName": "schema_type" }, "oneOf": [ { "$ref": "#/components/schemas/PublicClinicalDocumentDetail" }, { "$ref": "#/components/schemas/PublicAmbientTranscriptDocumentDetail" } ], "title": "Document" } }, "required": [ "document" ], "title": "PublicDocumentDetailResponse", "type": "object" }, "PublicDocumentMarkdownContent": { "additionalProperties": false, "description": "Markdown content returned for supported clinical documents.", "properties": { "format": { "const": "markdown", "default": "markdown", "description": "Content format. Public clinical document content is markdown.", "title": "Format", "type": "string" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Clinical document text when available.", "title": "Text" } }, "title": "PublicDocumentMarkdownContent", "type": "object" }, "PublicDocumentTranscriptResponse": { "additionalProperties": false, "description": "Public document transcript response.", "properties": { "document_id": { "description": "Opaque public document identifier.", "title": "Document Id", "type": "string" }, "encounter_id": { "description": "Opaque public encounter identifier.", "title": "Encounter Id", "type": "string" }, "transcript": { "$ref": "#/components/schemas/PublicFinalTranscript", "description": "Finalized transcript content." } }, "required": [ "document_id", "encounter_id", "transcript" ], "title": "PublicDocumentTranscriptResponse", "type": "object" }, "PublicEncounterDetailResponse": { "additionalProperties": false, "description": "Public encounter detail response.", "properties": { "encounter": { "$ref": "#/components/schemas/PublicEncounterSummary", "description": "Encounter summary and related document summaries." } }, "required": [ "encounter" ], "title": "PublicEncounterDetailResponse", "type": "object" }, "PublicEncounterDocumentSummary": { "additionalProperties": false, "description": "Document summary embedded in public encounter list and detail responses.", "properties": { "audio_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Audio duration in seconds when known for transcript documents.", "title": "Audio Duration Seconds" }, "document_id": { "description": "Opaque public document identifier.", "title": "Document Id", "type": "string" }, "schema_type": { "description": "Public document summary type. Billing and checklist values are summary-only and are not supported document-detail targets.", "enum": [ "document", "ambient_transcript", "billing", "encounter_checklist" ], "title": "Schema Type", "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document lifecycle status when available.", "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document title when available.", "title": "Title" }, "workflow_variant": { "anyOf": [ { "enum": [ "ambient", "phone_call" ], "type": "string" }, { "type": "null" } ], "description": "Ambient workflow variant when applicable.", "title": "Workflow Variant" } }, "required": [ "document_id", "schema_type" ], "title": "PublicEncounterDocumentSummary", "type": "object" }, "PublicEncounterListResponse": { "additionalProperties": false, "description": "Offset-paginated public encounter list response.", "properties": { "items": { "description": "Encounter summaries in the requested page.", "items": { "$ref": "#/components/schemas/PublicEncounterSummary" }, "title": "Items", "type": "array" }, "limit": { "description": "Limit used for the page.", "title": "Limit", "type": "integer" }, "offset": { "description": "Zero-based offset used for the page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total matching encounters at the time the query was evaluated.", "title": "Total", "type": "integer" } }, "required": [ "items", "limit", "offset", "total" ], "title": "PublicEncounterListResponse", "type": "object" }, "PublicEncounterSummary": { "additionalProperties": false, "description": "Public encounter summary with patient and document summary data.", "properties": { "created_at": { "description": "Encounter creation timestamp.", "format": "date-time", "title": "Created At", "type": "string" }, "date_of_service": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Encounter date of service when available.", "title": "Date Of Service" }, "documents": { "description": "Public document summaries associated with the encounter.", "items": { "$ref": "#/components/schemas/PublicEncounterDocumentSummary" }, "title": "Documents", "type": "array" }, "encounter_id": { "description": "Opaque public encounter identifier.", "title": "Encounter Id", "type": "string" }, "encounter_type": { "anyOf": [ { "enum": [ "ambient", "phone_call", "clinical_documentation", "billing", "checklist" ], "type": "string" }, { "type": "null" } ], "description": "Derived public encounter type. Null means no approved summary type could be derived from the encounter documents.", "title": "Encounter Type" }, "organization_id": { "description": "Opaque organization identifier that owns the encounter.", "title": "Organization Id", "type": "string" }, "patient": { "anyOf": [ { "$ref": "#/components/schemas/PublicPatientSummary" }, { "type": "null" } ], "description": "Patient summary when available for the encounter." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Encounter lifecycle status when available.", "title": "Status" }, "updated_at": { "description": "Encounter last-update timestamp.", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "encounter_id", "organization_id", "created_at", "updated_at" ], "title": "PublicEncounterSummary", "type": "object" }, "PublicFinalTranscript": { "additionalProperties": false, "description": "Finalized transcript content for an ambient transcript document.", "properties": { "audio_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Transcript audio duration in seconds when known.", "title": "Audio Duration Seconds" }, "provider": { "description": "Transcript provider label.", "title": "Provider", "type": "string" }, "turns": { "description": "Final transcript turns in chronological order.", "items": { "$ref": "#/components/schemas/PublicTranscriptTurn" }, "title": "Turns", "type": "array" } }, "required": [ "provider", "turns" ], "title": "PublicFinalTranscript", "type": "object" }, "PublicPatientSummary": { "additionalProperties": false, "description": "Patient summary fields returned in public encounter responses.", "properties": { "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Patient date of birth when available to the public contract.", "title": "Date Of Birth" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Patient first name when available to the public contract.", "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Patient last name when available to the public contract.", "title": "Last Name" }, "patient_id": { "description": "Opaque public patient identifier.", "title": "Patient Id", "type": "string" } }, "required": [ "patient_id" ], "title": "PublicPatientSummary", "type": "object" }, "PublicTranscriptTurn": { "additionalProperties": false, "description": "One finalized transcript speaker turn.", "properties": { "end": { "description": "Turn end time in seconds.", "title": "End", "type": "number" }, "speaker": { "description": "Speaker label for the transcript turn.", "title": "Speaker", "type": "string" }, "start": { "description": "Turn start time in seconds.", "title": "Start", "type": "number" }, "text": { "description": "Transcript text for the turn.", "title": "Text", "type": "string" } }, "required": [ "speaker", "text", "start", "end" ], "title": "PublicTranscriptTurn", "type": "object" }, "RecordingTranscriptReadyResources": { "additionalProperties": false, "properties": { "document_id": { "minLength": 1, "title": "Document Id", "type": "string" }, "encounter_id": { "minLength": 1, "title": "Encounter Id", "type": "string" } }, "required": [ "encounter_id", "document_id" ], "title": "RecordingTranscriptReadyResources", "type": "object" }, "RecordingTranscriptReadyWebhookEvent": { "additionalProperties": false, "properties": { "api_version": { "const": "2026-05-01", "title": "Api Version", "type": "string" }, "id": { "minLength": 1, "title": "Id", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "organization_id": { "minLength": 1, "title": "Organization Id", "type": "string" }, "resources": { "$ref": "#/components/schemas/RecordingTranscriptReadyResources" }, "type": { "const": "recording.transcript_ready", "title": "Type", "type": "string" } }, "required": [ "id", "type", "api_version", "occurred_at", "organization_id", "resources" ], "title": "RecordingTranscriptReadyWebhookEvent", "type": "object" } }, "securitySchemes": { "publicApiKeyBearer": { "bearerFormat": "API key", "description": "Send Authorization: Bearer from server-side code.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Curated public REST API for ChartHero API-key integrations, plus planned / not generally available public webhook reference material. Internal application and management surfaces are intentionally excluded.", "title": "ChartHero Public API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/external/v1/encounters": { "get": { "description": "List encounters available to the caller organization.\n\nRequired scopes: `encounters:read`, `patients:read`, `documents:read`.\n\nThe route is read-only and available only for approved organizations using organization-scoped API keys. Authorization, route availability, organization approval, and required scopes are checked before query parsing, unsupported-filter handling, or resource lookup.\n\nPagination is offset-based with limit default 50, limit range 1..100, offset default 0, and offset range 0..10000. Integers must be canonical decimal text. Results are ordered by created_at with encounter_id as a deterministic tie-breaker; sort_order defaults to desc. start_at is an inclusive timezone-aware ISO datetime lower bound on created_at; end_at is an exclusive timezone-aware ISO datetime upper bound. Offset pages are not snapshot-consistent across repeated calls.\n\nExample request: GET /external/v1/encounters?limit=50&offset=0&sort_order=desc.\n\nRepeated reads may record repeated disclosure events.", "operationId": "listPublicEncounters", "parameters": [ { "description": "Maximum number of encounters to return. Defaults to 50; allowed range is 1..100. Use canonical decimal integer text.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Zero-based offset into the encounter list. Defaults to 0; allowed range is 0..10000. Use canonical decimal integer text. Offset pagination is not snapshot-consistent across repeated calls.", "example": 0, "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "maximum": 10000, "minimum": 0, "type": "integer" } }, { "description": "Sort direction for created_at, with encounter_id as a deterministic tie-breaker. Defaults to desc.", "example": "desc", "in": "query", "name": "sort_order", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Inclusive created_at lower bound. Use a timezone-aware ISO datetime.", "example": "2026-05-01T00:00:00Z", "in": "query", "name": "start_at", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive created_at upper bound. Use a timezone-aware ISO datetime.", "example": "2026-06-01T00:00:00Z", "in": "query", "name": "end_at", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "encounterList": { "summary": "Encounter list page", "value": { "items": [ { "created_at": "2026-05-25T14:00:00Z", "date_of_service": "2026-05-25T14:00:00Z", "documents": [ { "audio_duration_seconds": 842.4, "document_id": "doc_synthetic_transcript_001", "schema_type": "ambient_transcript", "status": "completed", "title": "Ambient transcript", "workflow_variant": "ambient" } ], "encounter_id": "enc_synthetic_001", "encounter_type": "ambient", "organization_id": "org_synthetic_001", "patient": { "date_of_birth": "1900-01-01", "first_name": "Synthetic", "last_name": "Patient", "patient_id": "pat_synthetic_001" }, "status": "completed", "updated_at": "2026-05-25T15:00:00Z" } ], "limit": 50, "offset": 0, "total": 1 } } }, "schema": { "$ref": "#/components/schemas/PublicEncounterListResponse" } } }, "description": "A page of public encounter summaries." }, "400": { "content": { "application/json": { "examples": { "unsupported_filter": { "summary": "unsupported_filter", "value": { "error": "public_api_bad_request", "field": "owners", "message": "The request includes an unsupported filter.", "reason_code": "unsupported_filter" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 400.", "x-charthero-reason-codes": [ "unsupported_filter" ] }, "401": { "content": { "application/json": { "examples": { "api_keys_disabled": { "summary": "api_keys_disabled", "value": { "error": "api_key_unauthorized", "field": null, "message": "API-key authentication is disabled.", "reason_code": "api_keys_disabled" } }, "disabled_key": { "summary": "disabled_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is disabled.", "reason_code": "disabled_key" } }, "expired_key": { "summary": "expired_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has expired.", "reason_code": "expired_key" } }, "invalid_key": { "summary": "invalid_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is invalid.", "reason_code": "invalid_key" } }, "malformed_token": { "summary": "malformed_token", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key token is malformed.", "reason_code": "malformed_token" } }, "missing_bearer": { "summary": "missing_bearer", "value": { "error": "api_key_unauthorized", "field": null, "message": "A bearer API key is required.", "reason_code": "missing_bearer" } }, "revoked_key": { "summary": "revoked_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has been revoked.", "reason_code": "revoked_key" } }, "test_prefix_not_allowed": { "summary": "test_prefix_not_allowed", "value": { "error": "api_key_unauthorized", "field": null, "message": "Test API keys are not allowed in this environment.", "reason_code": "test_prefix_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 401.", "x-charthero-reason-codes": [ "missing_bearer", "api_keys_disabled", "test_prefix_not_allowed", "malformed_token", "invalid_key", "disabled_key", "revoked_key", "expired_key" ] }, "403": { "content": { "application/json": { "examples": { "missing_scope": { "summary": "missing_scope", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is missing a required scope.", "reason_code": "missing_scope" } }, "org_scope_only_required": { "summary": "org_scope_only_required", "value": { "error": "api_key_forbidden", "field": null, "message": "Organization-scoped API keys are required.", "reason_code": "org_scope_only_required" } }, "organization_not_allowlisted": { "summary": "organization_not_allowlisted", "value": { "error": "api_key_forbidden", "field": null, "message": "The organization is not allowlisted for this public API route.", "reason_code": "organization_not_allowlisted" } }, "route_not_allowed": { "summary": "route_not_allowed", "value": { "error": "api_key_forbidden", "field": null, "message": "This public API route is not enabled.", "reason_code": "route_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 403.", "x-charthero-reason-codes": [ "org_scope_only_required", "route_not_allowed", "missing_scope", "organization_not_allowlisted" ] }, "422": { "content": { "application/json": { "examples": { "invalid_limit": { "summary": "invalid_limit", "value": { "error": "api_key_validation_failed", "field": "limit", "message": "The limit query parameter is invalid.", "reason_code": "invalid_limit" } }, "invalid_offset": { "summary": "invalid_offset", "value": { "error": "api_key_validation_failed", "field": "offset", "message": "The offset query parameter is invalid.", "reason_code": "invalid_offset" } }, "invalid_query": { "summary": "invalid_query", "value": { "error": "api_key_validation_failed", "field": "start_at", "message": "The query parameters are invalid.", "reason_code": "invalid_query" } }, "invalid_sort": { "summary": "invalid_sort", "value": { "error": "api_key_validation_failed", "field": "sort_order", "message": "The sort_order query parameter is invalid.", "reason_code": "invalid_sort" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 422.", "x-charthero-reason-codes": [ "invalid_query", "invalid_limit", "invalid_offset", "invalid_sort" ] }, "503": { "content": { "application/json": { "examples": { "digest_key_unavailable": { "summary": "digest_key_unavailable", "value": { "error": "public_api_unavailable", "field": null, "message": "API-key verification is temporarily unavailable.", "reason_code": "digest_key_unavailable" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 503.", "x-charthero-reason-codes": [ "digest_key_unavailable" ] } }, "security": [ { "publicApiKeyBearer": [] } ], "summary": "List public encounters", "tags": [ "Public API" ], "x-charthero-required-scopes": [ "encounters:read", "patients:read", "documents:read" ] } }, "/external/v1/encounters/{encounter_id}": { "get": { "description": "Read one encounter available to the caller organization.\n\nRequired scopes: `encounters:read`, `patients:read`, `documents:read`.\n\nThe route is read-only and available only for approved organizations using organization-scoped API keys. Authorization, route availability, organization approval, and required scopes are checked before unsupported query parameters or resource lookup. Demo/training and cross-organization encounters are not returned through this route.\n\nExample request: GET /external/v1/encounters/enc_synthetic_001.\n\nPath IDs are opaque ChartHero IDs. Treat the example values as illustrative strings only; no prefix or format semantics are guaranteed.", "operationId": "getPublicEncounter", "parameters": [ { "description": "Opaque encounter identifier returned by public encounter routes. Example values are illustrative only and do not define an ID format.", "example": "enc_synthetic_001", "in": "path", "name": "encounter_id", "required": true, "schema": { "title": "Encounter Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "encounterDetail": { "summary": "Encounter detail", "value": { "encounter": { "created_at": "2026-05-25T14:00:00Z", "date_of_service": "2026-05-25T14:00:00Z", "documents": [ { "audio_duration_seconds": null, "document_id": "doc_synthetic_note_001", "schema_type": "document", "status": null, "title": "Progress note", "workflow_variant": null } ], "encounter_id": "enc_synthetic_001", "encounter_type": "clinical_documentation", "organization_id": "org_synthetic_001", "patient": { "date_of_birth": "1900-01-01", "first_name": "Synthetic", "last_name": "Patient", "patient_id": "pat_synthetic_001" }, "status": "completed", "updated_at": "2026-05-25T15:00:00Z" } } } }, "schema": { "$ref": "#/components/schemas/PublicEncounterDetailResponse" } } }, "description": "One public encounter with patient and document summaries." }, "400": { "content": { "application/json": { "examples": { "unsupported_filter": { "summary": "unsupported_filter", "value": { "error": "public_api_bad_request", "field": "owners", "message": "The request includes an unsupported filter.", "reason_code": "unsupported_filter" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 400.", "x-charthero-reason-codes": [ "unsupported_filter" ] }, "401": { "content": { "application/json": { "examples": { "api_keys_disabled": { "summary": "api_keys_disabled", "value": { "error": "api_key_unauthorized", "field": null, "message": "API-key authentication is disabled.", "reason_code": "api_keys_disabled" } }, "disabled_key": { "summary": "disabled_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is disabled.", "reason_code": "disabled_key" } }, "expired_key": { "summary": "expired_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has expired.", "reason_code": "expired_key" } }, "invalid_key": { "summary": "invalid_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is invalid.", "reason_code": "invalid_key" } }, "malformed_token": { "summary": "malformed_token", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key token is malformed.", "reason_code": "malformed_token" } }, "missing_bearer": { "summary": "missing_bearer", "value": { "error": "api_key_unauthorized", "field": null, "message": "A bearer API key is required.", "reason_code": "missing_bearer" } }, "revoked_key": { "summary": "revoked_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has been revoked.", "reason_code": "revoked_key" } }, "test_prefix_not_allowed": { "summary": "test_prefix_not_allowed", "value": { "error": "api_key_unauthorized", "field": null, "message": "Test API keys are not allowed in this environment.", "reason_code": "test_prefix_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 401.", "x-charthero-reason-codes": [ "missing_bearer", "api_keys_disabled", "test_prefix_not_allowed", "malformed_token", "invalid_key", "disabled_key", "revoked_key", "expired_key" ] }, "403": { "content": { "application/json": { "examples": { "cross_organization_denied": { "summary": "cross_organization_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is not authorized for this encounter.", "reason_code": "cross_organization_denied" } }, "demo_training_denied": { "summary": "demo_training_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "Demo and training encounters are not available through this API.", "reason_code": "demo_training_denied" } }, "missing_scope": { "summary": "missing_scope", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is missing a required scope.", "reason_code": "missing_scope" } }, "org_scope_only_required": { "summary": "org_scope_only_required", "value": { "error": "api_key_forbidden", "field": null, "message": "Organization-scoped API keys are required.", "reason_code": "org_scope_only_required" } }, "organization_not_allowlisted": { "summary": "organization_not_allowlisted", "value": { "error": "api_key_forbidden", "field": null, "message": "The organization is not allowlisted for this public API route.", "reason_code": "organization_not_allowlisted" } }, "route_not_allowed": { "summary": "route_not_allowed", "value": { "error": "api_key_forbidden", "field": null, "message": "This public API route is not enabled.", "reason_code": "route_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 403.", "x-charthero-reason-codes": [ "org_scope_only_required", "route_not_allowed", "missing_scope", "organization_not_allowlisted", "cross_organization_denied", "demo_training_denied" ] }, "404": { "content": { "application/json": { "examples": { "encounter_not_found": { "summary": "encounter_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The encounter was not found.", "reason_code": "encounter_not_found" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 404.", "x-charthero-reason-codes": [ "encounter_not_found" ] }, "503": { "content": { "application/json": { "examples": { "digest_key_unavailable": { "summary": "digest_key_unavailable", "value": { "error": "public_api_unavailable", "field": null, "message": "API-key verification is temporarily unavailable.", "reason_code": "digest_key_unavailable" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 503.", "x-charthero-reason-codes": [ "digest_key_unavailable" ] } }, "security": [ { "publicApiKeyBearer": [] } ], "summary": "Get a public encounter", "tags": [ "Public API" ], "x-charthero-required-scopes": [ "encounters:read", "patients:read", "documents:read" ] } }, "/external/v1/encounters/{encounter_id}/documents/{document_id}": { "get": { "description": "Read one supported document that belongs to an available encounter.\n\nRequired scopes: `encounters:read`, `documents:read`.\n\nThe route is read-only and available only for approved organizations using organization-scoped API keys. Authorization, route availability, organization approval, and required scopes are checked before unsupported query parameters or resource lookup.\n\nA document with schema_type=document returns clinical markdown content. A document with schema_type=ambient_transcript returns transcript metadata only; use the transcript route for transcript turns and the audio route for audio URL access. Billing and checklist summaries are not supported document-detail targets.\n\nExample request: GET /external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_note_001.\n\nPath IDs are opaque ChartHero IDs. Treat the example values as illustrative strings only; no prefix or format semantics are guaranteed.", "operationId": "getPublicDocument", "parameters": [ { "description": "Opaque encounter identifier returned by public encounter routes. Example values are illustrative only and do not define an ID format.", "example": "enc_synthetic_001", "in": "path", "name": "encounter_id", "required": true, "schema": { "title": "Encounter Id", "type": "string" } }, { "description": "Opaque document identifier returned in public encounter document summaries. Example values are illustrative only and do not define an ID format.", "example": "doc_synthetic_transcript_001", "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "ambientTranscriptMetadata": { "summary": "Ambient transcript metadata", "value": { "document": { "audio_duration_seconds": 842.4, "created_at": "2026-05-25T14:00:00Z", "document_id": "doc_synthetic_transcript_001", "encounter_id": "enc_synthetic_001", "schema_type": "ambient_transcript", "status": "completed", "title": "Ambient transcript", "updated_at": "2026-05-25T15:00:00Z", "workflow_variant": "ambient" } } }, "clinicalDocument": { "summary": "Clinical document content", "value": { "document": { "content": { "format": "markdown", "text": "Synthetic assessment and plan text." }, "created_at": "2026-05-25T14:30:00Z", "document_id": "doc_synthetic_note_001", "encounter_id": "enc_synthetic_001", "schema_type": "document", "status": null, "title": "Progress note", "updated_at": "2026-05-25T15:00:00Z", "workflow_variant": null } } } }, "schema": { "$ref": "#/components/schemas/PublicDocumentDetailResponse" } } }, "description": "One supported public document: clinical content or ambient transcript metadata." }, "400": { "content": { "application/json": { "examples": { "unsupported_document_type": { "summary": "unsupported_document_type", "value": { "error": "public_api_bad_request", "field": null, "message": "The document type is not supported for this public API route.", "reason_code": "unsupported_document_type" } }, "unsupported_filter": { "summary": "unsupported_filter", "value": { "error": "public_api_bad_request", "field": "owners", "message": "The request includes an unsupported filter.", "reason_code": "unsupported_filter" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 400.", "x-charthero-reason-codes": [ "unsupported_filter", "unsupported_document_type" ] }, "401": { "content": { "application/json": { "examples": { "api_keys_disabled": { "summary": "api_keys_disabled", "value": { "error": "api_key_unauthorized", "field": null, "message": "API-key authentication is disabled.", "reason_code": "api_keys_disabled" } }, "disabled_key": { "summary": "disabled_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is disabled.", "reason_code": "disabled_key" } }, "expired_key": { "summary": "expired_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has expired.", "reason_code": "expired_key" } }, "invalid_key": { "summary": "invalid_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is invalid.", "reason_code": "invalid_key" } }, "malformed_token": { "summary": "malformed_token", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key token is malformed.", "reason_code": "malformed_token" } }, "missing_bearer": { "summary": "missing_bearer", "value": { "error": "api_key_unauthorized", "field": null, "message": "A bearer API key is required.", "reason_code": "missing_bearer" } }, "revoked_key": { "summary": "revoked_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has been revoked.", "reason_code": "revoked_key" } }, "test_prefix_not_allowed": { "summary": "test_prefix_not_allowed", "value": { "error": "api_key_unauthorized", "field": null, "message": "Test API keys are not allowed in this environment.", "reason_code": "test_prefix_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 401.", "x-charthero-reason-codes": [ "missing_bearer", "api_keys_disabled", "test_prefix_not_allowed", "malformed_token", "invalid_key", "disabled_key", "revoked_key", "expired_key" ] }, "403": { "content": { "application/json": { "examples": { "cross_organization_denied": { "summary": "cross_organization_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is not authorized for this encounter.", "reason_code": "cross_organization_denied" } }, "demo_training_denied": { "summary": "demo_training_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "Demo and training encounters are not available through this API.", "reason_code": "demo_training_denied" } }, "missing_scope": { "summary": "missing_scope", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is missing a required scope.", "reason_code": "missing_scope" } }, "org_scope_only_required": { "summary": "org_scope_only_required", "value": { "error": "api_key_forbidden", "field": null, "message": "Organization-scoped API keys are required.", "reason_code": "org_scope_only_required" } }, "organization_not_allowlisted": { "summary": "organization_not_allowlisted", "value": { "error": "api_key_forbidden", "field": null, "message": "The organization is not allowlisted for this public API route.", "reason_code": "organization_not_allowlisted" } }, "route_not_allowed": { "summary": "route_not_allowed", "value": { "error": "api_key_forbidden", "field": null, "message": "This public API route is not enabled.", "reason_code": "route_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 403.", "x-charthero-reason-codes": [ "org_scope_only_required", "route_not_allowed", "missing_scope", "organization_not_allowlisted", "cross_organization_denied", "demo_training_denied" ] }, "404": { "content": { "application/json": { "examples": { "document_not_found": { "summary": "document_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The document was not found.", "reason_code": "document_not_found" } }, "encounter_not_found": { "summary": "encounter_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The encounter was not found.", "reason_code": "encounter_not_found" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 404.", "x-charthero-reason-codes": [ "encounter_not_found", "document_not_found" ] }, "503": { "content": { "application/json": { "examples": { "digest_key_unavailable": { "summary": "digest_key_unavailable", "value": { "error": "public_api_unavailable", "field": null, "message": "API-key verification is temporarily unavailable.", "reason_code": "digest_key_unavailable" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 503.", "x-charthero-reason-codes": [ "digest_key_unavailable" ] } }, "security": [ { "publicApiKeyBearer": [] } ], "summary": "Get a public document", "tags": [ "Public API" ], "x-charthero-required-scopes": [ "encounters:read", "documents:read" ] } }, "/external/v1/encounters/{encounter_id}/documents/{document_id}/audio": { "get": { "description": "Request a short-lived signed URL for audio associated with an ambient transcript document.\n\nRequired scopes: `encounters:read`, `documents:read`, `recordings:read`.\n\nThe route is read-only and available only for approved organizations using organization-scoped API keys. Authorization, route availability, organization approval, and required scopes are checked before unsupported query parameters or resource lookup.\n\nThe document must be an ambient transcript with completed transcript content and recording-backed audio. Each successful call can issue a new URL, and expires_at can differ across retries. Use the document route for metadata and the transcript route for transcript turns.\n\nExample request: GET /external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_transcript_001/audio.\n\nPath IDs are opaque ChartHero IDs. Treat the example values as illustrative strings only; no prefix or format semantics are guaranteed.", "operationId": "getPublicDocumentAudioUrl", "parameters": [ { "description": "Opaque encounter identifier returned by public encounter routes. Example values are illustrative only and do not define an ID format.", "example": "enc_synthetic_001", "in": "path", "name": "encounter_id", "required": true, "schema": { "title": "Encounter Id", "type": "string" } }, { "description": "Opaque document identifier returned in public encounter document summaries. Example values are illustrative only and do not define an ID format.", "example": "doc_synthetic_transcript_001", "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "documentAudioUrl": { "summary": "Short-lived audio URL", "value": { "audio_url": "https://media.charthero.example/signed-recording.wav?token=example", "expires_at": "2026-05-25T15:15:00Z" } } }, "schema": { "$ref": "#/components/schemas/PublicDocumentAudioResponse" } } }, "description": "A short-lived signed URL for document audio." }, "400": { "content": { "application/json": { "examples": { "audio_not_available_for_document": { "summary": "audio_not_available_for_document", "value": { "error": "public_api_bad_request", "field": null, "message": "Audio is not available for this document.", "reason_code": "audio_not_available_for_document" } }, "unsupported_document_type": { "summary": "unsupported_document_type", "value": { "error": "public_api_bad_request", "field": null, "message": "The document type is not supported for this public API route.", "reason_code": "unsupported_document_type" } }, "unsupported_filter": { "summary": "unsupported_filter", "value": { "error": "public_api_bad_request", "field": "owners", "message": "The request includes an unsupported filter.", "reason_code": "unsupported_filter" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 400.", "x-charthero-reason-codes": [ "unsupported_filter", "unsupported_document_type", "audio_not_available_for_document" ] }, "401": { "content": { "application/json": { "examples": { "api_keys_disabled": { "summary": "api_keys_disabled", "value": { "error": "api_key_unauthorized", "field": null, "message": "API-key authentication is disabled.", "reason_code": "api_keys_disabled" } }, "disabled_key": { "summary": "disabled_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is disabled.", "reason_code": "disabled_key" } }, "expired_key": { "summary": "expired_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has expired.", "reason_code": "expired_key" } }, "invalid_key": { "summary": "invalid_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is invalid.", "reason_code": "invalid_key" } }, "malformed_token": { "summary": "malformed_token", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key token is malformed.", "reason_code": "malformed_token" } }, "missing_bearer": { "summary": "missing_bearer", "value": { "error": "api_key_unauthorized", "field": null, "message": "A bearer API key is required.", "reason_code": "missing_bearer" } }, "revoked_key": { "summary": "revoked_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has been revoked.", "reason_code": "revoked_key" } }, "test_prefix_not_allowed": { "summary": "test_prefix_not_allowed", "value": { "error": "api_key_unauthorized", "field": null, "message": "Test API keys are not allowed in this environment.", "reason_code": "test_prefix_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 401.", "x-charthero-reason-codes": [ "missing_bearer", "api_keys_disabled", "test_prefix_not_allowed", "malformed_token", "invalid_key", "disabled_key", "revoked_key", "expired_key" ] }, "403": { "content": { "application/json": { "examples": { "cross_organization_denied": { "summary": "cross_organization_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is not authorized for this encounter.", "reason_code": "cross_organization_denied" } }, "demo_training_denied": { "summary": "demo_training_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "Demo and training encounters are not available through this API.", "reason_code": "demo_training_denied" } }, "missing_scope": { "summary": "missing_scope", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is missing a required scope.", "reason_code": "missing_scope" } }, "org_scope_only_required": { "summary": "org_scope_only_required", "value": { "error": "api_key_forbidden", "field": null, "message": "Organization-scoped API keys are required.", "reason_code": "org_scope_only_required" } }, "organization_not_allowlisted": { "summary": "organization_not_allowlisted", "value": { "error": "api_key_forbidden", "field": null, "message": "The organization is not allowlisted for this public API route.", "reason_code": "organization_not_allowlisted" } }, "route_not_allowed": { "summary": "route_not_allowed", "value": { "error": "api_key_forbidden", "field": null, "message": "This public API route is not enabled.", "reason_code": "route_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 403.", "x-charthero-reason-codes": [ "org_scope_only_required", "route_not_allowed", "missing_scope", "organization_not_allowlisted", "cross_organization_denied", "demo_training_denied" ] }, "404": { "content": { "application/json": { "examples": { "audio_not_found": { "summary": "audio_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The audio object was not found.", "reason_code": "audio_not_found" } }, "document_not_found": { "summary": "document_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The document was not found.", "reason_code": "document_not_found" } }, "encounter_not_found": { "summary": "encounter_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The encounter was not found.", "reason_code": "encounter_not_found" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 404.", "x-charthero-reason-codes": [ "encounter_not_found", "document_not_found", "audio_not_found" ] }, "503": { "content": { "application/json": { "examples": { "audio_storage_unavailable": { "summary": "audio_storage_unavailable", "value": { "error": "public_api_unavailable", "field": null, "message": "Audio storage is temporarily unavailable.", "reason_code": "audio_storage_unavailable" } }, "digest_key_unavailable": { "summary": "digest_key_unavailable", "value": { "error": "public_api_unavailable", "field": null, "message": "API-key verification is temporarily unavailable.", "reason_code": "digest_key_unavailable" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 503.", "x-charthero-reason-codes": [ "digest_key_unavailable", "audio_storage_unavailable" ] } }, "security": [ { "publicApiKeyBearer": [] } ], "summary": "Get a public document audio URL", "tags": [ "Public API" ], "x-charthero-required-scopes": [ "encounters:read", "documents:read", "recordings:read" ] } }, "/external/v1/encounters/{encounter_id}/documents/{document_id}/transcript": { "get": { "description": "Read finalized transcript turns for an ambient transcript document.\n\nRequired scopes: `encounters:read`, `documents:read`.\n\nThe route is read-only and available only for approved organizations using organization-scoped API keys. Authorization, route availability, organization approval, and required scopes are checked before unsupported query parameters or resource lookup.\n\nThe document must be an ambient transcript with a completed, finalized transcript. The document-detail route returns only ambient transcript metadata; this route returns speaker turns and timing.\n\nExample request: GET /external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_transcript_001/transcript.\n\nPath IDs are opaque ChartHero IDs. Treat the example values as illustrative strings only; no prefix or format semantics are guaranteed.", "operationId": "getPublicDocumentTranscript", "parameters": [ { "description": "Opaque encounter identifier returned by public encounter routes. Example values are illustrative only and do not define an ID format.", "example": "enc_synthetic_001", "in": "path", "name": "encounter_id", "required": true, "schema": { "title": "Encounter Id", "type": "string" } }, { "description": "Opaque document identifier returned in public encounter document summaries. Example values are illustrative only and do not define an ID format.", "example": "doc_synthetic_transcript_001", "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "documentTranscript": { "summary": "Final transcript turns", "value": { "document_id": "doc_synthetic_transcript_001", "encounter_id": "enc_synthetic_001", "transcript": { "audio_duration_seconds": 842.4, "provider": "deepgram", "turns": [ { "end": 1.6, "speaker": "clinician", "start": 0, "text": "Synthetic clinician sample." }, { "end": 3.1, "speaker": "patient", "start": 1.8, "text": "Synthetic patient sample." } ] } } } }, "schema": { "$ref": "#/components/schemas/PublicDocumentTranscriptResponse" } } }, "description": "Finalized transcript turns for an ambient transcript document." }, "400": { "content": { "application/json": { "examples": { "unsupported_document_type": { "summary": "unsupported_document_type", "value": { "error": "public_api_bad_request", "field": null, "message": "The document type is not supported for this public API route.", "reason_code": "unsupported_document_type" } }, "unsupported_filter": { "summary": "unsupported_filter", "value": { "error": "public_api_bad_request", "field": "owners", "message": "The request includes an unsupported filter.", "reason_code": "unsupported_filter" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 400.", "x-charthero-reason-codes": [ "unsupported_filter", "unsupported_document_type" ] }, "401": { "content": { "application/json": { "examples": { "api_keys_disabled": { "summary": "api_keys_disabled", "value": { "error": "api_key_unauthorized", "field": null, "message": "API-key authentication is disabled.", "reason_code": "api_keys_disabled" } }, "disabled_key": { "summary": "disabled_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is disabled.", "reason_code": "disabled_key" } }, "expired_key": { "summary": "expired_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has expired.", "reason_code": "expired_key" } }, "invalid_key": { "summary": "invalid_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key is invalid.", "reason_code": "invalid_key" } }, "malformed_token": { "summary": "malformed_token", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key token is malformed.", "reason_code": "malformed_token" } }, "missing_bearer": { "summary": "missing_bearer", "value": { "error": "api_key_unauthorized", "field": null, "message": "A bearer API key is required.", "reason_code": "missing_bearer" } }, "revoked_key": { "summary": "revoked_key", "value": { "error": "api_key_unauthorized", "field": null, "message": "The API key has been revoked.", "reason_code": "revoked_key" } }, "test_prefix_not_allowed": { "summary": "test_prefix_not_allowed", "value": { "error": "api_key_unauthorized", "field": null, "message": "Test API keys are not allowed in this environment.", "reason_code": "test_prefix_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 401.", "x-charthero-reason-codes": [ "missing_bearer", "api_keys_disabled", "test_prefix_not_allowed", "malformed_token", "invalid_key", "disabled_key", "revoked_key", "expired_key" ] }, "403": { "content": { "application/json": { "examples": { "cross_organization_denied": { "summary": "cross_organization_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is not authorized for this encounter.", "reason_code": "cross_organization_denied" } }, "demo_training_denied": { "summary": "demo_training_denied", "value": { "error": "api_key_forbidden", "field": null, "message": "Demo and training encounters are not available through this API.", "reason_code": "demo_training_denied" } }, "missing_scope": { "summary": "missing_scope", "value": { "error": "api_key_forbidden", "field": null, "message": "The API key is missing a required scope.", "reason_code": "missing_scope" } }, "org_scope_only_required": { "summary": "org_scope_only_required", "value": { "error": "api_key_forbidden", "field": null, "message": "Organization-scoped API keys are required.", "reason_code": "org_scope_only_required" } }, "organization_not_allowlisted": { "summary": "organization_not_allowlisted", "value": { "error": "api_key_forbidden", "field": null, "message": "The organization is not allowlisted for this public API route.", "reason_code": "organization_not_allowlisted" } }, "route_not_allowed": { "summary": "route_not_allowed", "value": { "error": "api_key_forbidden", "field": null, "message": "This public API route is not enabled.", "reason_code": "route_not_allowed" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 403.", "x-charthero-reason-codes": [ "org_scope_only_required", "route_not_allowed", "missing_scope", "organization_not_allowlisted", "cross_organization_denied", "demo_training_denied" ] }, "404": { "content": { "application/json": { "examples": { "document_not_found": { "summary": "document_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The document was not found.", "reason_code": "document_not_found" } }, "encounter_not_found": { "summary": "encounter_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The encounter was not found.", "reason_code": "encounter_not_found" } }, "transcript_not_found": { "summary": "transcript_not_found", "value": { "error": "public_api_not_found", "field": null, "message": "The finalized transcript was not found.", "reason_code": "transcript_not_found" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 404.", "x-charthero-reason-codes": [ "encounter_not_found", "document_not_found", "transcript_not_found" ] }, "503": { "content": { "application/json": { "examples": { "digest_key_unavailable": { "summary": "digest_key_unavailable", "value": { "error": "public_api_unavailable", "field": null, "message": "API-key verification is temporarily unavailable.", "reason_code": "digest_key_unavailable" } } }, "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } }, "description": "Public API error response for HTTP 503.", "x-charthero-reason-codes": [ "digest_key_unavailable" ] } }, "security": [ { "publicApiKeyBearer": [] } ], "summary": "Get a public document transcript", "tags": [ "Public API" ], "x-charthero-required-scopes": [ "encounters:read", "documents:read" ] } } }, "servers": [ { "description": "Public API origin; deployment hostname intentionally not fixed by DOCS-FR-002", "url": "/" } ], "tags": [ { "description": "Public API-key REST routes.", "name": "Public API" }, { "description": "Public outbound webhook contracts.", "name": "Webhooks" } ], "webhooks": { "recording.transcript_ready": { "post": { "description": "Planned and not generally available. Receivers should dedupe business work by body id or ChartHero-Event-Id. Current receiver correlation status is not_confirmed_runtime_blocked. Launch requires subscription activation provenance for approved follow-up routes, least-privilege receiver API-key scopes, receiver correlation, signing setup, and outbound PHI audit readiness.", "operationId": "receiveRecordingTranscriptReadyWebhook", "parameters": [ { "description": "Matches the JSON body id.", "in": "header", "name": "ChartHero-Event-Id", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Stable for one event/endpoint delivery and reused across retries.", "in": "header", "name": "ChartHero-Delivery-Id", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Decimal Unix epoch seconds. Receivers should reject values outside a 300 second local-clock tolerance.", "in": "header", "name": "ChartHero-Timestamp", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "description": "HMAC-SHA256 signature over {timestamp}.{raw_request_body}, formatted with the v1= prefix.", "in": "header", "name": "ChartHero-Signature", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Matches the JSON body api_version.", "in": "header", "name": "ChartHero-Webhook-Version", "required": true, "schema": { "enum": [ "2026-05-01" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "recordingTranscriptReady": { "summary": "Minimal pointer notification", "value": { "api_version": "2026-05-01", "id": "evt_recording_transcript_ready_01", "occurred_at": "2026-05-01T15:29:55Z", "organization_id": "org_synthetic_webhook_001", "resources": { "document_id": "doc_synthetic_transcript_001", "encounter_id": "enc_synthetic_webhook_001" }, "type": "recording.transcript_ready" } } }, "schema": { "$ref": "#/components/schemas/RecordingTranscriptReadyWebhookEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Any 2xx response is treated as receiver success; no response body is required." } }, "security": [], "summary": "Receive recording transcript-ready notifications", "tags": [ "Webhooks" ], "x-charthero-correlation-status": "not_confirmed_runtime_blocked", "x-charthero-follow-up": { "audio_scope_policy": "recordings:read is required only when the audio follow-up route is approved.", "candidate_routes": [ { "required_scopes": [ "encounters:read", "patients:read", "documents:read" ], "route": "GET /external/v1/encounters/{encounter_id}" }, { "required_scopes": [ "encounters:read", "documents:read" ], "route": "GET /external/v1/encounters/{encounter_id}/documents/{document_id}" }, { "required_scopes": [ "encounters:read", "documents:read" ], "route": "GET /external/v1/encounters/{encounter_id}/documents/{document_id}/transcript" }, { "required_scopes": [ "encounters:read", "documents:read", "recordings:read" ], "route": "GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio" } ], "launch_readiness_model": "subscription_activation_provenance", "runtime_status": "planned_not_generally_available", "scope_policy": "Receiver API keys require only the union of scopes for approved follow-up routes." }, "x-charthero-launch-readiness": { "activation_atomicity": "Activation records readiness and provenance atomically with the active subscription revision.", "activation_provenance_required": [ "subscription_activation_readiness", "approved_follow_up_route_subset", "route_family_readiness_allowlist", "least_privilege_receiver_api_key_scope_union", "receiver_api_key_id_or_key_family", "receiver_api_key_secret_handoff", "webhook_signing_secret_setup", "receiver_correlation_confirmed", "network_egress_allowlisting_when_applicable", "outbound_webhook_phi_audit_schema_and_sender_wiring", "supported_event_api_version_payload_mode" ], "clinical_subscriptions_default": "disabled", "readiness_revocation": "Disable affected clinical subscriptions and explicitly cancel already-created non-terminal unsucceeded delivery work, including pending, currently leased sending, and expired/stale sending deliveries.", "setup_flags_scope": "Management/setup availability flags control setup surfaces only, not publisher, fanout sweeper, dispatcher, renderer, signer, HTTP transport, or PHI audit emission.", "supported_event_api_version_payload_mode": { "api_version": "2026-05-01", "event_type": "recording.transcript_ready", "payload_mode": "thin" } }, "x-charthero-receiver-response": { "body_required": false, "success": "any_2xx" }, "x-charthero-retry": { "dedupe_header": "ChartHero-Event-Id", "dedupe_key": "id", "delivery": "at_least_once", "delivery_id_semantics": "ChartHero-Delivery-Id is stable for one event/endpoint delivery, reused across retries, and support/debug metadata only.", "event_id_semantics": "ChartHero-Event-Id equals body id and is the receiver business idempotency key.", "receiver_success": "any_2xx", "retryable": [ "connection_error", "dns_error", "tls_error", "timeout", "408", "409", "425", "429", "5xx" ], "terminal": [ "1xx", "3xx", "400", "401", "403", "404", "other_non_transient_4xx" ] }, "x-charthero-runtime-status": "planned_not_generally_available", "x-charthero-signature": { "algorithm": "HMAC-SHA256", "header_format": "v1=", "required_headers": [ "ChartHero-Event-Id", "ChartHero-Delivery-Id", "ChartHero-Timestamp", "ChartHero-Signature", "ChartHero-Webhook-Version" ], "signature_input": "{timestamp}.{raw_request_body}", "timestamp_format": "unix_epoch_seconds", "timestamp_tolerance_seconds": 300, "version": "v1" }, "x-charthero-signature-example": { "example_secret": "whsec_test_secret_do_not_use", "headers": { "ChartHero-Event-Id": "evt_recording_transcript_ready_01", "ChartHero-Delivery-Id": "whd_recording_transcript_ready_01", "ChartHero-Timestamp": "1777649400", "ChartHero-Signature": "v1=a3bb0750eef64758be4a034aaff5dd5774c21bf7fe25083b51d61ba0214c0419", "ChartHero-Webhook-Version": "2026-05-01" }, "payload_sha256": "974a7ced2a89e7eadee2e44a49dd21c1c479e84617252a7b365a3a48628abd87", "raw_request_body": "{\"id\":\"evt_recording_transcript_ready_01\",\"type\":\"recording.transcript_ready\",\"api_version\":\"2026-05-01\",\"occurred_at\":\"2026-05-01T15:29:55Z\",\"organization_id\":\"org_synthetic_webhook_001\",\"resources\":{\"encounter_id\":\"enc_synthetic_webhook_001\",\"document_id\":\"doc_synthetic_transcript_001\"}}", "signature_header": "v1=a3bb0750eef64758be4a034aaff5dd5774c21bf7fe25083b51d61ba0214c0419", "signature_input": "1777649400.{\"id\":\"evt_recording_transcript_ready_01\",\"type\":\"recording.transcript_ready\",\"api_version\":\"2026-05-01\",\"occurred_at\":\"2026-05-01T15:29:55Z\",\"organization_id\":\"org_synthetic_webhook_001\",\"resources\":{\"encounter_id\":\"enc_synthetic_webhook_001\",\"document_id\":\"doc_synthetic_transcript_001\"}}", "timestamp": "1777649400" } } } } }