Skip to main content
GET
Get Transcriptions by Appointment

Overview

Returns the transcription(s) stored for a specific appointment, looked up by appointment_id, together with the parent appointment’s current processing state (appointmentStatus, errorReason, and appointmentUpdatedAt). This lets a client render the transcribing / processing / error state in a single request. If the appointment exists, the caller must be its owning doctor. Because only one transcription may exist per appointment, the returned data array contains zero or one transcription in practice.
The path value is an appointment ObjectId. The endpoint returns the transcriptions whose appointment_id matches it.

Authentication

string
required
Bearer JWT token. The calling user is derived from the token.

Path Parameters

string
required
The appointment ObjectId. Transcriptions are looked up by appointment_id; if the appointment exists the caller must be its owning doctor.

Response

boolean
required
Indicates whether the request succeeded.
array
Array of transcription objects for the appointment (0 or 1 element in practice).
string
The parent appointment’s current status (e.g. transcribing, processing, error_transcription), or null if the appointment does not exist.
string
The parent appointment’s error reason, or null when there is none.
string
The parent appointment’s last-update timestamp (ISO 8601), or null if the appointment does not exist. Useful for detecting a stalled status.
Additional fields (for example __v) may appear on the transcription object. Treat any field not documented here as opaque.

Example Request

Example Response

Success (200) - Transcription Present
Success (200) - No Transcription On File

Error Responses

401 Unauthorized
403 Forbidden (not the owning doctor)
The Unauthorized response uses the message field; handler-level errors use the error field. Unexpected server errors return 500 { "success": false, "error": "<message>" }. When the appointment does not exist the ownership check is skipped and the three appointment fields (appointmentStatus, errorReason, appointmentUpdatedAt) are returned as null.

Behavior Notes

  • Lookup by appointment: Transcriptions are located by appointment_id; the path value is an appointment id.
  • Combined state: The appointment’s status, error_reason, and updatedAt are returned alongside the transcription so a client can render processing state in one call.
  • Ownership: If the appointment exists, only its owning doctor may read the transcription; otherwise the request returns 403 Forbidden.
  • At most one transcription: Because creation rejects duplicates, data holds 0 or 1 element.