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

# List Doctor's Appointments

> Retrieve the authenticated doctor's appointments, optionally filtered by date range

## Overview

Returns every appointment owned by the authenticated doctor. The doctor is
identified from the JWT — there is no user id parameter. Results are scoped to
the caller: you only ever see your own appointments.

An optional date range can be applied with the `from` and `to` query parameters
(used by the calendar view). Unparseable dates are silently ignored.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authenticated access. The doctor id is taken from the token.

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

## Query Parameters

<ParamField query="from" type="string">
  ISO datetime. Lower bound (inclusive) on the appointment `date`. Ignored if it
  cannot be parsed.
</ParamField>

<ParamField query="to" type="string">
  ISO datetime. Upper bound (exclusive) on the appointment `date`. Ignored if it
  cannot be parsed.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="array">
  Array of appointment objects owned by the caller.

  <Expandable title="Appointment Object">
    <ResponseField name="_id" type="string">
      Unique appointment identifier (ObjectId).
    </ResponseField>

    <ResponseField name="name" type="string">
      Appointment title.
    </ResponseField>

    <ResponseField name="date" type="string">
      Appointment date, serialized as a full ISO datetime
      (e.g. `2026-07-15T00:00:00.000Z`).
    </ResponseField>

    <ResponseField name="time" type="string">
      Wall-clock time, `HH:mm`.
    </ResponseField>

    <ResponseField name="recording_id" type="string">
      Associated recording id, if any.
    </ResponseField>

    <ResponseField name="status" type="string">
      Recording lifecycle status. Common values: `planned`, `recording`,
      `transcribing`, `processing`, `finished`, `error`, `error_transcription`,
      `audio_upload_failed`. Not strictly enforced — treat unknown values as
      opaque.
    </ResponseField>

    <ResponseField name="error_reason" type="string | null">
      Human-readable reason when processing failed; otherwise `null`.
    </ResponseField>

    <ResponseField name="doctor_id" type="string">
      Owning doctor's user id.
    </ResponseField>

    <ResponseField name="language" type="string">
      Language code used for note generation. Default `de`.
    </ResponseField>

    <ResponseField name="notes_type" type="string | null">
      Notes template key. Default `null` (the service selects a template).
    </ResponseField>

    <ResponseField name="appointment_type" type="string">
      Free-form appointment type. Default `in_person`.
    </ResponseField>

    <ResponseField name="room" type="string | null">
      Room / location label, or `null` when none is assigned.
    </ResponseField>

    <ResponseField name="duration_minutes" type="number | null">
      Appointment duration in minutes, or `null` when unset.
    </ResponseField>

    <ResponseField name="deletionDate" type="string">
      ISO datetime at which the appointment is scheduled for automatic deletion.
    </ResponseField>

    <ResponseField name="case_id" type="string | null">
      Case grouping id for follow-up linking, or `null`.
    </ResponseField>

    <ResponseField name="booking_status" type="string">
      Booking lifecycle state (a separate axis from `status`). Default `none`
      for plain appointments; non-`none` values indicate an online or
      externally-synced booking.
    </ResponseField>

    <ResponseField name="booking" type="object | null">
      Booking subdocument for appointments that carry booking metadata,
      otherwise `null`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO last-update timestamp.
    </ResponseField>

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

<Note>
  Additional fields may appear on the appointment object depending on how it was
  created (for example provenance fields on externally-synced appointments).
  Treat any field not documented here as opaque.
</Note>

## Example Request

<RequestExample>
  ```bash curl theme={null}
  curl -X GET "https://app.medisync.me/api/appointments/doctors?from=2026-07-01T00:00:00Z&to=2026-08-01T00:00:00Z" \
    -H "Authorization: Bearer <JWT>"
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "_id": "65f8a1b2c3d4e5f6789012ef",
        "name": "Allgemeine Beratung",
        "date": "2026-07-15T00:00:00.000Z",
        "time": "14:30",
        "recording_id": "rec_123",
        "status": "recording",
        "error_reason": null,
        "doctor_id": "65f0a1b2c3d4e5f678901234",
        "language": "de",
        "notes_type": null,
        "appointment_type": "in_person",
        "room": null,
        "duration_minutes": null,
        "deletionDate": "2026-07-29T00:00:00.000Z",
        "case_id": null,
        "booking_status": "none",
        "booking": null,
        "createdAt": "2026-07-02T09:12:00.000Z",
        "updatedAt": "2026-07-02T09:12:00.000Z",
        "__v": 0
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

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

  ```json 401 Session Revoked theme={null}
  {
    "success": false,
    "message": "Session ended on this device because you signed in elsewhere.",
    "code": "SESSION_REVOKED"
  }
  ```

  ```json 400 Server Error theme={null}
  {
    "success": false,
    "error": "appointments query failed"
  }
  ```
</ResponseExample>

<Note>
  A missing or invalid Bearer token returns `401` with a `message` key (not
  `error`). Only one active session per device set is allowed; signing in
  elsewhere revokes the previous session and returns the `SESSION_REVOKED` code.
  On a server-side failure the `error` field carries the raw error message.
</Note>