> ## 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 Documents by Appointment

> List the documents you own on a given appointment

## Overview

Returns the documents attached to a specific appointment that are **owned by the authenticated doctor**. The query is scoped to both the appointment ID and the calling doctor, so documents attached by another doctor are not returned.

The response is always an array. If nothing matches, it returns `200` with an empty `data` array.

<Info>
  This is a read endpoint and is **not** plan-gated: it keeps working even for accounts that do not have the `documents.attach_additional` feature, so previously attached documents remain accessible.
</Info>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authenticated access. The doctor's ID is extracted from the JWT token and used to scope results.

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

## Path Parameters

<ParamField path="id" type="string" required>
  The appointment ID (ObjectId) whose documents should be listed. Only documents owned by the authenticated doctor are returned.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  Array of document records owned by the authenticated doctor on this appointment. Empty when none match.

  <Expandable title="Document Object">
    <ResponseField name="_id" type="string">
      Unique document identifier (ObjectId)
    </ResponseField>

    <ResponseField name="appointment_id" type="string">
      The appointment this document is attached to
    </ResponseField>

    <ResponseField name="document_url" type="string">
      Opaque storage URL for the document
    </ResponseField>

    <ResponseField name="document_key" type="string">
      Storage key. Format: `{appointment_id}_{timestamp}_{original_filename}`
    </ResponseField>

    <ResponseField name="doctor_id" type="string">
      ObjectId of the owning doctor
    </ResponseField>

    <ResponseField name="file_name" type="string">
      Original filename of the document
    </ResponseField>

    <ResponseField name="title" type="string">
      Display title (defaults to the original filename)
    </ResponseField>

    <ResponseField name="file_type" type="string">
      Inferred short file type (e.g. `pdf`, `png`, `jpeg`, `webp`)
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      MIME type of the stored file
    </ResponseField>

    <ResponseField name="source" type="string">
      Origin of the document (e.g. `upload`)
    </ResponseField>

    <ResponseField name="extraction_status" type="string">
      Text-extraction state (e.g. `pending`, `done`)
    </ResponseField>

    <ResponseField name="include_in_context" type="boolean">
      Whether the document is included when building context
    </ResponseField>

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

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

    <ResponseField name="__v" type="number">
      Internal record version
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message (only present when `success` is `false`)
</ResponseField>

<Note>
  Additional fields may be present on each document object and should be treated as opaque. There is no pagination and no guaranteed sort order.
</Note>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET \
    'https://app.medisync.me/api/documents/665e0b9d3f2a1c4d8e7f0a12' \
    -H 'Authorization: Bearer your_jwt_token_here'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.medisync.me/api/documents/665e0b9d3f2a1c4d8e7f0a12',
    {
      method: 'GET',
      headers: { Authorization: 'Bearer your_jwt_token_here' },
    }
  );

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

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

  response = requests.get(
      'https://app.medisync.me/api/documents/665e0b9d3f2a1c4d8e7f0a12',
      headers={'Authorization': 'Bearer your_jwt_token_here'},
  )

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

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "_id": "66a3f1c2b8e4d21f9c0a7b31",
        "appointment_id": "665e0b9d3f2a1c4d8e7f0a12",
        "document_url": "https://storage.medisync.me/665e0b9d3f2a1c4d8e7f0a12_1719920400000_lab_results.pdf",
        "document_key": "665e0b9d3f2a1c4d8e7f0a12_1719920400000_lab_results.pdf",
        "doctor_id": "6512a7c9e4b0a1f2d3c45678",
        "file_name": "lab_results.pdf",
        "title": "lab_results.pdf",
        "file_type": "pdf",
        "mime_type": "application/pdf",
        "source": "upload",
        "extraction_status": "done",
        "include_in_context": true,
        "createdAt": "2026-07-02T14:30:00.000Z",
        "updatedAt": "2026-07-02T14:31:12.000Z",
        "__v": 0
      }
    ]
  }
  ```

  ```json Empty result theme={null}
  {
    "success": true,
    "data": []
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Query error theme={null}
  {
    "success": false,
    "error": "Error fetching documents by appointment ID"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>