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

# Scheduling

> Manage appointments, appointment types, reminders, and doctor availability via the Management API

# Scheduling

Administer your organisation's scheduling configuration with an API key instead of
the admin interface. You can list and cancel scheduled appointments, manage
appointment types and their reminders, and configure each doctor's recurring
availability rules.

All endpoints are scoped to the organisation that owns the API key. UIDs that
belong to another organisation are treated as not found.

## Permissions

Scheduling endpoints are gated by two permissions:

* `scheduling:read` — required for all read (`GET`) endpoints.
* `scheduling:admin` — required for all write endpoints (`POST`, `PATCH`, `DELETE`).

A key with `scheduling:admin` is not automatically granted `scheduling:read`;
add both if you need to read and write. Contact your RxScale account manager to
adjust permissions.

All requests authenticate with the `X-API-Key` header. See
[Authentication](/authentication) for details.

## Appointments

### List Appointments

```bash theme={null}
GET /v1/management/scheduling/appointments
```

Returns a paginated list of scheduled appointments for the organisation.

**Required permission:** `scheduling:read`

<ParamField query="page" type="integer" default="0">
  Page number (0-indexed)
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of appointments per page
</ParamField>

<ParamField query="doctor_uid" type="string">
  Filter appointments by doctor UID
</ParamField>

<ParamField query="patient_uid" type="string">
  Filter appointments by patient UID
</ParamField>

<ParamField query="status" type="string">
  Filter by appointment status. One of `held`, `confirmed`, `cancelled`,
  `expired`, `completed`, `no_show`, or `all`. When omitted, the default
  server-side filtering applies.
</ParamField>

<ParamField query="from" type="integer">
  Filter appointments starting at or after this Unix timestamp
</ParamField>

<ParamField query="to" type="integer">
  Filter appointments starting at or before this Unix timestamp. Must be
  greater than `from` when both are supplied.
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointments?page=0&limit=25&status=confirmed" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

```json theme={null}
{
  "data": [
    {
      "uid": "mtg-abc123",
      "status": "confirmed",
      "doctor_uid": "doc-456",
      "doctor_display_name": "Dr. Schmidt",
      "patient_uid": "pat-789",
      "patient_display_name": "Jane Doe",
      "appointment_type_uid": "apt-001",
      "appointment_type_name": "Initial consultation",
      "visit_reason": "Medication review before changing dosage",
      "meeting_type": "CONSULTATION",
      "meeting_format": "DIGITAL",
      "start_date": 1712300000,
      "end_date": 1712301800,
      "created_at": 1712200000,
      "cancelled_at": null,
      "cancellation_reason": null
    }
  ],
  "totalRegistries": 42,
  "totalPages": 2
}
```

#### Response Fields

| Field                          | Type            | Description                                                                                                      |
| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `data[].uid`                   | string          | Scheduled meeting UID                                                                                            |
| `data[].status`                | string          | Appointment status (`held`, `confirmed`, `cancelled`, `expired`, `completed`, `no_show`)                         |
| `data[].doctor_uid`            | string          | Doctor UID                                                                                                       |
| `data[].doctor_display_name`   | string          | Doctor display name                                                                                              |
| `data[].patient_uid`           | string          | Patient UID                                                                                                      |
| `data[].patient_display_name`  | string          | Patient display name                                                                                             |
| `data[].appointment_type_uid`  | string \| null  | Appointment type UID, if any                                                                                     |
| `data[].appointment_type_name` | string \| null  | Appointment type name, if any                                                                                    |
| `data[].visit_reason`          | string \| null  | Optional reason supplied during booking. May also be shown in reminder notifications and synced calendar invites |
| `data[].meeting_type`          | string          | Meeting type (e.g. `CONSULTATION`, `FOLLOW_UP`, `INITIAL`, `REVIEW`, `ON_DEMAND`)                                |
| `data[].meeting_format`        | string          | Meeting format (`DIGITAL`, `IN_PERSON`)                                                                          |
| `data[].start_date`            | integer         | Start time (Unix timestamp)                                                                                      |
| `data[].end_date`              | integer         | End time (Unix timestamp)                                                                                        |
| `data[].created_at`            | integer         | Creation timestamp (Unix)                                                                                        |
| `data[].cancelled_at`          | integer \| null | Cancellation timestamp (Unix), if cancelled                                                                      |
| `data[].cancellation_reason`   | string \| null  | Reason supplied at cancellation, if cancelled                                                                    |
| `totalRegistries`              | integer         | Total number of appointments matching the filter                                                                 |
| `totalPages`                   | integer         | Total number of pages                                                                                            |

### Cancel an Appointment

```bash theme={null}
POST /v1/management/scheduling/appointments/{meeting_uid}/cancel
```

Cancels a scheduled appointment and records the supplied reason.

**Required permission:** `scheduling:admin`

<ParamField path="meeting_uid" type="string" required>
  The scheduled meeting UID
</ParamField>

<ParamField body="reason" type="string" required>
  Reason for cancelling the appointment (must not be empty)
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointments/mtg-abc123/cancel" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Patient requested cancellation"
  }'
```

#### Response

```json theme={null}
{
  "appointment_uid": "mtg-abc123",
  "status": "cancelled",
  "cancelled_at": 1712250000,
  "cancellation_reason": "Patient requested cancellation"
}
```

## Appointment Types

An appointment type defines a bookable kind of meeting (duration, hold behaviour,
room and rebooking strategy).

### List Appointment Types

```bash theme={null}
GET /v1/management/scheduling/appointment-types
```

**Required permission:** `scheduling:read`

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointment-types" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

```json theme={null}
{
  "data": [
    {
      "uid": "apt-001",
      "organisation_uid": "org-123",
      "name": "Initial consultation",
      "meeting_type": "CONSULTATION",
      "duration_minutes": 30,
      "hold_ttl_seconds": 900,
      "booking_min_notice_minutes": 10,
      "cancellation_min_notice_minutes": 60,
      "rebooking_min_notice_minutes": 120,
      "room_strategy": "persistent_per_provider",
      "rebooking_mode": "same_doctor_only",
      "doctor_assignment_mode": "all_available_doctors",
      "allow_patient_rebooking": true,
      "active": true,
      "created_at": 1712100000,
      "updated_at": 1712100000
    }
  ]
}
```

### Create an Appointment Type

```bash theme={null}
POST /v1/management/scheduling/appointment-types
```

**Required permission:** `scheduling:admin`

<ParamField body="name" type="string" required>
  Display name (1–255 characters)
</ParamField>

<ParamField body="meeting_type" type="string" required>
  Meeting type. One of `CONSULTATION`, `FOLLOW_UP`, `INITIAL`, `REVIEW`,
  `ON_DEMAND`.
</ParamField>

<ParamField body="duration_minutes" type="integer" required>
  Appointment duration in minutes (1–1440)
</ParamField>

<ParamField body="hold_ttl_seconds" type="integer" required>
  How long a tentative hold survives before expiring, in seconds (1–86400)
</ParamField>

<ParamField body="booking_min_notice_minutes" type="integer" default="0">
  Default minimum notice required before patients can book this appointment type,
  in minutes. Doctor-specific settings can override this value.
</ParamField>

<ParamField body="cancellation_min_notice_minutes" type="integer" default="0">
  Minimum notice required to cancel, in minutes (≥ 0)
</ParamField>

<ParamField body="rebooking_min_notice_minutes" type="integer" default="0">
  Minimum notice required to rebook, in minutes (≥ 0)
</ParamField>

<ParamField body="room_strategy" type="string" required>
  Room allocation strategy. One of `persistent_per_provider`,
  `per_appointment`.
</ParamField>

<ParamField body="rebooking_mode" type="string" required>
  Rebooking mode. One of `same_doctor_only`,
  `any_doctor_same_organisation`.
</ParamField>

<ParamField body="doctor_assignment_mode" type="string" default="all_available_doctors">
  Controls which doctors can offer this appointment type. Use
  `all_available_doctors` to include every doctor with availability, or
  `selected_doctors_only` to require an active doctor-specific setting.
</ParamField>

<ParamField body="allow_patient_rebooking" type="boolean" default="false">
  Whether patients may rebook their own appointments of this type
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Whether the appointment type is bookable
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointment-types" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initial consultation",
    "meeting_type": "CONSULTATION",
    "duration_minutes": 30,
    "hold_ttl_seconds": 900,
    "booking_min_notice_minutes": 10,
    "cancellation_min_notice_minutes": 60,
    "rebooking_min_notice_minutes": 120,
    "room_strategy": "persistent_per_provider",
    "rebooking_mode": "same_doctor_only",
    "doctor_assignment_mode": "all_available_doctors",
    "allow_patient_rebooking": true,
    "active": true
  }'
```

Returns `201 Created` with the created appointment type (same shape as a list
entry).

### Update an Appointment Type

```bash theme={null}
PATCH /v1/management/scheduling/appointment-types/{appointment_type_uid}
```

Partial update — only the fields you send are changed. All body fields are
optional and accept the same values and ranges as on create.

**Required permission:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  The appointment type UID
</ParamField>

<ParamField body="name" type="string">
  Display name (1–255 characters)
</ParamField>

<ParamField body="meeting_type" type="string">
  One of `CONSULTATION`, `FOLLOW_UP`, `INITIAL`, `REVIEW`, `ON_DEMAND`
</ParamField>

<ParamField body="duration_minutes" type="integer">
  Appointment duration in minutes (1–1440)
</ParamField>

<ParamField body="hold_ttl_seconds" type="integer">
  Hold lifetime in seconds (1–86400)
</ParamField>

<ParamField body="booking_min_notice_minutes" type="integer">
  Default minimum booking notice in minutes (≥ 0)
</ParamField>

<ParamField body="cancellation_min_notice_minutes" type="integer">
  Minimum cancellation notice in minutes (≥ 0)
</ParamField>

<ParamField body="rebooking_min_notice_minutes" type="integer">
  Minimum rebooking notice in minutes (≥ 0)
</ParamField>

<ParamField body="room_strategy" type="string">
  One of `persistent_per_provider`, `per_appointment`
</ParamField>

<ParamField body="rebooking_mode" type="string">
  One of `same_doctor_only`, `any_doctor_same_organisation`
</ParamField>

<ParamField body="doctor_assignment_mode" type="string">
  One of `all_available_doctors`, `selected_doctors_only`
</ParamField>

<ParamField body="allow_patient_rebooking" type="boolean">
  Whether patients may rebook their own appointments of this type
</ParamField>

<ParamField body="active" type="boolean">
  Whether the appointment type is bookable
</ParamField>

#### Example Request

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_minutes": 45,
    "active": false
  }'
```

Returns `200 OK` with the updated appointment type.

### Delete an Appointment Type

```bash theme={null}
DELETE /v1/management/scheduling/appointment-types/{appointment_type_uid}
```

**Required permission:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  The appointment type UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001" \
  -H "X-API-Key: your-api-key-here"
```

Returns `204 No Content` on success.

## Reminders

Reminders are configured per appointment type and notify a recipient role a fixed
number of minutes before the appointment starts.

### List Reminders

```bash theme={null}
GET /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders
```

**Required permission:** `scheduling:read`

<ParamField path="appointment_type_uid" type="string" required>
  The appointment type UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

```json theme={null}
{
  "data": [
    {
      "uid": "rem-001",
      "appointment_type_uid": "apt-001",
      "recipient_role": "patient",
      "minutes_before": 1440,
      "send_email": true,
      "send_sms": false,
      "active": true
    }
  ]
}
```

#### Response Fields

| Field                         | Type    | Description                                    |
| ----------------------------- | ------- | ---------------------------------------------- |
| `data[].uid`                  | string  | Reminder UID                                   |
| `data[].appointment_type_uid` | string  | Parent appointment type UID                    |
| `data[].recipient_role`       | string  | Who is notified (`patient`, `doctor`, `admin`) |
| `data[].minutes_before`       | integer | Minutes before the appointment to send         |
| `data[].send_email`           | boolean | Whether to send an email                       |
| `data[].send_sms`             | boolean | Whether to send an SMS                         |
| `data[].active`               | boolean | Whether the reminder is active                 |

### Create a Reminder

```bash theme={null}
POST /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders
```

**Required permission:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  The appointment type UID
</ParamField>

<ParamField body="recipient_role" type="string" required>
  Who is notified. One of `patient`, `doctor`, `admin`.
</ParamField>

<ParamField body="minutes_before" type="integer" required>
  Minutes before the appointment to send the reminder (1–86400, i.e. up to 60
  days)
</ParamField>

<ParamField body="send_email" type="boolean" default="false">
  Whether to send an email
</ParamField>

<ParamField body="send_sms" type="boolean" default="false">
  Whether to send an SMS
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Whether the reminder is active
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_role": "patient",
    "minutes_before": 1440,
    "send_email": true,
    "send_sms": false,
    "active": true
  }'
```

Returns `201 Created` with the created reminder (same shape as a list entry).

### Update a Reminder

```bash theme={null}
PATCH /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
```

Partial update — only the fields you send are changed.

**Required permission:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  The appointment type UID
</ParamField>

<ParamField path="reminder_uid" type="string" required>
  The reminder UID
</ParamField>

<ParamField body="recipient_role" type="string">
  One of `patient`, `doctor`, `admin`
</ParamField>

<ParamField body="minutes_before" type="integer">
  Minutes before the appointment to send the reminder (1–86400)
</ParamField>

<ParamField body="send_email" type="boolean">
  Whether to send an email
</ParamField>

<ParamField body="send_sms" type="boolean">
  Whether to send an SMS
</ParamField>

<ParamField body="active" type="boolean">
  Whether the reminder is active
</ParamField>

#### Example Request

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders/rem-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "minutes_before": 60,
    "send_sms": true
  }'
```

Returns `200 OK` with the updated reminder.

### Delete a Reminder

```bash theme={null}
DELETE /v1/management/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
```

**Required permission:** `scheduling:admin`

<ParamField path="appointment_type_uid" type="string" required>
  The appointment type UID
</ParamField>

<ParamField path="reminder_uid" type="string" required>
  The reminder UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/appointment-types/apt-001/reminders/rem-001" \
  -H "X-API-Key: your-api-key-here"
```

Returns `204 No Content` on success.

## Availability Rules

Availability rules define a doctor's recurring weekly bookable windows. Times are
expressed as minutes from midnight (for example, `540` is 09:00 and `1020` is
17:00).

### List Availability Rules

```bash theme={null}
GET /v1/management/scheduling/doctors/{doctor_uid}/availability-rules
```

**Required permission:** `scheduling:read`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

```json theme={null}
{
  "data": [
    {
      "uid": "rule-001",
      "doctor_uid": "doc-456",
      "weekday": 0,
      "start_time": 540,
      "end_time": 1020,
      "buffer_minutes": 10,
      "valid_from": null,
      "valid_until": null,
      "active": true
    }
  ]
}
```

#### Response Fields

| Field                   | Type            | Description                                            |
| ----------------------- | --------------- | ------------------------------------------------------ |
| `data[].uid`            | string          | Availability rule UID                                  |
| `data[].doctor_uid`     | string          | Doctor UID                                             |
| `data[].weekday`        | integer         | Day of week (0 = Monday … 6 = Sunday)                  |
| `data[].start_time`     | integer         | Start of the window, in minutes from midnight (0–1440) |
| `data[].end_time`       | integer         | End of the window, in minutes from midnight (0–1440)   |
| `data[].buffer_minutes` | integer         | Buffer between appointments, in minutes                |
| `data[].valid_from`     | integer \| null | Optional start of validity (Unix timestamp)            |
| `data[].valid_until`    | integer \| null | Optional end of validity (Unix timestamp)              |
| `data[].active`         | boolean         | Whether the rule is active                             |

### Create an Availability Rule

```bash theme={null}
POST /v1/management/scheduling/doctors/{doctor_uid}/availability-rules
```

**Required permission:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField body="weekday" type="integer" required>
  Day of week (0 = Monday … 6 = Sunday)
</ParamField>

<ParamField body="start_time" type="integer" required>
  Start of the window, in minutes from midnight (0–1440)
</ParamField>

<ParamField body="end_time" type="integer" required>
  End of the window, in minutes from midnight (0–1440)
</ParamField>

<ParamField body="buffer_minutes" type="integer" default="0">
  Buffer between appointments, in minutes (≥ 0)
</ParamField>

<ParamField body="valid_from" type="integer">
  Optional start of validity (Unix timestamp)
</ParamField>

<ParamField body="valid_until" type="integer">
  Optional end of validity (Unix timestamp)
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Whether the rule is active
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "weekday": 0,
    "start_time": 540,
    "end_time": 1020,
    "buffer_minutes": 10,
    "active": true
  }'
```

Returns `201 Created` with the created availability rule (same shape as a list
entry).

### Update an Availability Rule

```bash theme={null}
PATCH /v1/management/scheduling/doctors/{doctor_uid}/availability-rules/{rule_uid}
```

Partial update — only the fields you send are changed. To remove an existing
validity bound, send the corresponding `clear_*` flag rather than a value.

**Required permission:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField path="rule_uid" type="string" required>
  The availability rule UID
</ParamField>

<ParamField body="weekday" type="integer">
  Day of week (0 = Monday … 6 = Sunday)
</ParamField>

<ParamField body="start_time" type="integer">
  Start of the window, in minutes from midnight (0–1440)
</ParamField>

<ParamField body="end_time" type="integer">
  End of the window, in minutes from midnight (0–1440)
</ParamField>

<ParamField body="buffer_minutes" type="integer">
  Buffer between appointments, in minutes (≥ 0)
</ParamField>

<ParamField body="valid_from" type="integer">
  Set the start of validity (Unix timestamp)
</ParamField>

<ParamField body="valid_until" type="integer">
  Set the end of validity (Unix timestamp)
</ParamField>

<ParamField body="active" type="boolean">
  Whether the rule is active
</ParamField>

<ParamField body="clear_valid_from" type="boolean" default="false">
  Clear the existing `valid_from` bound (set it to null)
</ParamField>

<ParamField body="clear_valid_until" type="boolean" default="false">
  Clear the existing `valid_until` bound (set it to null)
</ParamField>

#### Example Request

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": 960,
    "clear_valid_until": true
  }'
```

Returns `200 OK` with the updated availability rule.

### Delete an Availability Rule

```bash theme={null}
DELETE /v1/management/scheduling/doctors/{doctor_uid}/availability-rules/{rule_uid}
```

**Required permission:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField path="rule_uid" type="string" required>
  The availability rule UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-rules/rule-001" \
  -H "X-API-Key: your-api-key-here"
```

Returns `204 No Content` on success.

## Availability Date Overrides

Date overrides set a doctor's availability for a **specific calendar date**,
replacing their recurring weekly rules on that date. Each override is either a
**time window** (custom hours that day) or a **day off** (no bookable slots that
day). On any date that has at least one override, the doctor's recurring rules
are suppressed and only the overrides apply.

* `date` is the **UTC-midnight Unix timestamp** of the calendar date — a multiple
  of `86400` (for example, `1749427200` is 2025-06-09 00:00:00 UTC).
* `start_time` / `end_time` are minutes from midnight (for example, `480` is
  08:00 and `720` is 12:00). For a day off, both are `null`.

### List Date Overrides

```bash theme={null}
GET /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides
```

**Required permission:** `scheduling:read`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField query="from" type="integer">
  Only return overrides on or after this UTC-midnight epoch
</ParamField>

<ParamField query="to" type="integer">
  Only return overrides on or before this UTC-midnight epoch
</ParamField>

<ParamField query="page" type="integer" default="0">
  Zero-indexed page number
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size (maximum 200)
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides?from=1749427200&limit=50" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

The list is paginated, and a single request may span **at most \~6 months**. Omit
both `from` and `to` for "today onward"; pass one to anchor the window, or both to
choose a range — a span wider than \~6 months is trimmed from the `to` end.
`totalRegistries` is the number of overrides matching the (clamped) window and
`totalPages` is `ceil(totalRegistries / limit)`.

```json theme={null}
{
  "data": [
    {
      "uid": "ovr-001",
      "doctor_uid": "doc-456",
      "date": 1749427200,
      "start_time": 480,
      "end_time": 720,
      "buffer_minutes": 0
    },
    {
      "uid": "ovr-002",
      "doctor_uid": "doc-456",
      "date": 1749513600,
      "start_time": null,
      "end_time": null,
      "buffer_minutes": 0
    }
  ],
  "totalRegistries": 2,
  "totalPages": 1
}
```

#### Response Fields

| Field                   | Type            | Description                                                                  |
| ----------------------- | --------------- | ---------------------------------------------------------------------------- |
| `data[].uid`            | string          | Date override UID                                                            |
| `data[].doctor_uid`     | string          | Doctor UID                                                                   |
| `data[].date`           | integer         | UTC-midnight epoch of the calendar date (a multiple of 86400)                |
| `data[].start_time`     | integer \| null | Start of the window, in minutes from midnight (0–1440); `null` for a day off |
| `data[].end_time`       | integer \| null | End of the window, in minutes from midnight (0–1440); `null` for a day off   |
| `data[].buffer_minutes` | integer         | Buffer between appointments, in minutes                                      |

### Create a Date Override

```bash theme={null}
POST /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides
```

**Required permission:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField body="date" type="integer" required>
  UTC-midnight epoch of the calendar date (a multiple of 86400)
</ParamField>

<ParamField body="day_off" type="boolean" default="false">
  If true, the date is fully unavailable — omit `start_time`/`end_time`
</ParamField>

<ParamField body="start_time" type="integer">
  Start of the window, in minutes from midnight (0–1440). Required unless `day_off` is true
</ParamField>

<ParamField body="end_time" type="integer">
  End of the window, in minutes from midnight (0–1440). Required unless `day_off` is true
</ParamField>

<ParamField body="buffer_minutes" type="integer" default="0">
  Buffer between appointments, in minutes (≥ 0)
</ParamField>

#### Example Request — custom hours

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": 1749427200,
    "start_time": 480,
    "end_time": 720
  }'
```

#### Example Request — day off

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": 1749513600,
    "day_off": true
  }'
```

Returns `201 Created` with the created date override (same shape as a list
entry). Adding a day off clears any existing windows on that date, and adding a
window clears an existing day-off marker.

### Update a Date Override

```bash theme={null}
PATCH /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides/{override_uid}
```

Partial update — only the fields you send are changed. Send `day_off: true` to
turn the date into a day off (clearing its window).

**Required permission:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField path="override_uid" type="string" required>
  The date override UID
</ParamField>

<ParamField body="date" type="integer">
  UTC-midnight epoch of the calendar date (a multiple of 86400)
</ParamField>

<ParamField body="day_off" type="boolean" default="false">
  If true, clear the date's window and mark it a day off
</ParamField>

<ParamField body="start_time" type="integer">
  Start of the window, in minutes from midnight (0–1440)
</ParamField>

<ParamField body="end_time" type="integer">
  End of the window, in minutes from midnight (0–1440)
</ParamField>

<ParamField body="buffer_minutes" type="integer">
  Buffer between appointments, in minutes (≥ 0)
</ParamField>

#### Example Request

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides/ovr-001" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": 540,
    "end_time": 660
  }'
```

Returns `200 OK` with the updated date override.

### Delete a Date Override

```bash theme={null}
DELETE /v1/management/scheduling/doctors/{doctor_uid}/availability-date-overrides/{override_uid}
```

**Required permission:** `scheduling:admin`

<ParamField path="doctor_uid" type="string" required>
  The doctor UID
</ParamField>

<ParamField path="override_uid" type="string" required>
  The date override UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/scheduling/doctors/doc-456/availability-date-overrides/ovr-001" \
  -H "X-API-Key: your-api-key-here"
```

Returns `204 No Content` on success. The date returns to the doctor's recurring
availability.