> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medisync.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Transcriptions by Appointment

> Retrieve the transcription for an appointment along with the appointment's current processing state.

## 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.

<Info>
  The path value is an **appointment** ObjectId. The endpoint returns the transcriptions whose `appointment_id` matches it.
</Info>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer JWT token. The calling user is derived from the token.

  ```
  Authorization: Bearer <JWT>
  ```
</ParamField>

## Path Parameters

<ParamField path="appointmentId" type="string" required>
  The appointment ObjectId. Transcriptions are looked up by `appointment_id`; if the appointment exists the caller must be its owning doctor.

  ```
  665f8a1b2c3d4e5f6789012f3
  ```
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="array">
  Array of transcription objects for the appointment (0 or 1 element in practice).

  <Expandable title="Transcription Object">
    <ResponseField name="_id" type="string">
      Unique transcription identifier.
    </ResponseField>

    <ResponseField name="appointment_id" type="string">
      The associated appointment ObjectId.
    </ResponseField>

    <ResponseField name="transcription" type="array">
      Ordered array of transcript segment objects, e.g. `{ "sender": "speaker_0", "message": "...", "start_time": "00:00:05,800" }`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Creation timestamp (ISO 8601).
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Last-update timestamp (ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appointmentStatus" type="string">
  The parent appointment's current status (e.g. `transcribing`, `processing`, `error_transcription`), or `null` if the appointment does not exist.
</ResponseField>

<ResponseField name="errorReason" type="string">
  The parent appointment's error reason, or `null` when there is none.
</ResponseField>

<ResponseField name="appointmentUpdatedAt" type="string">
  The parent appointment's last-update timestamp (ISO 8601), or `null` if the appointment does not exist. Useful for detecting a stalled status.
</ResponseField>

<Info>
  Additional fields (for example `__v`) may appear on the transcription object. Treat any field not documented here as opaque.
</Info>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    'https://app.medisync.me/api/transcriptions/665f8a1b2c3d4e5f6789012f3' \
    -H 'Authorization: Bearer <JWT>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.medisync.me/api/transcriptions/665f8a1b2c3d4e5f6789012f3',
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer <JWT>'
      }
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {'Authorization': 'Bearer <JWT>'}

  response = requests.get(
      'https://app.medisync.me/api/transcriptions/665f8a1b2c3d4e5f6789012f3',
      headers=headers
  )

  result = response.json()
  ```
</CodeGroup>

## Example Response

```json Success (200) - Transcription Present theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "665f8a1b2c3d4e5f6789012f7",
      "appointment_id": "665f8a1b2c3d4e5f6789012f3",
      "transcription": [
        { "sender": "speaker_0", "message": "Guten Tag, was fuehrt Sie zu mir?", "start_time": "00:00:01,200" },
        { "sender": "speaker_1", "message": "Ich habe seit heute Morgen Brustschmerzen.", "start_time": "00:00:05,800" }
      ],
      "createdAt": "2026-06-30T10:30:00.000Z",
      "updatedAt": "2026-06-30T10:30:00.000Z"
    }
  ],
  "appointmentStatus": "processing",
  "errorReason": null,
  "appointmentUpdatedAt": "2026-06-30T10:31:00.000Z"
}
```

```json Success (200) - No Transcription On File theme={null}
{
  "success": true,
  "data": [],
  "appointmentStatus": "transcribing",
  "errorReason": null,
  "appointmentUpdatedAt": "2026-06-30T10:30:00.000Z"
}
```

## Error Responses

```json 401 Unauthorized theme={null}
{
  "success": false,
  "message": "Unauthorized"
}
```

```json 403 Forbidden (not the owning doctor) theme={null}
{
  "success": false,
  "error": "Forbidden"
}
```

<Note>
  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`.
</Note>

## 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.