Bookings, conflicts, and availability

GET/api/v1/appointments

Lists appointments starting inside a time window, ordered by start time.

The window is half-open: an appointment is included when its startAt falls in [from, to). An appointment that started before from and is still running is not returned.

`to` must be after `from`, and the window may span at most 370 days; outside that it is 400 `validation_failed`. Send both with a `Z` or an explicit offset, since a bare local time is ambiguous. Appointments of every status are returned, so filter client-side if you only want the confirmed ones.

Query parameters

Response · 200

{
  "data": {
    "appointments": [
      {
        "id": "a7c30e51-....",
        "type": "appointment",
        "startAt": "2026-07-08T10:00:00.000Z",
        "endAt": "2026-07-08T11:00:00.000Z"
      }
    ]
  },
  "requestId": "req_5f2c1e40-...."
}

Errors

POST/api/v1/appointments/series

Books one appointment and its repeats in a single transaction: a course of sessions.

Takes the create body without `type` and `status` (a course is an appointment, and the practice booking it makes it confirmed), plus `repeat`: `everyWeeks` 1 to 52, optional `weekdays` 0 (Sunday) to 6, and exactly one of `count` (2 to 52, counting the first) or `until` (YYYY-MM-DD, inclusive).

The rule is expanded on the practice's own clock, so a course at 09:00 stays at 09:00 after the clocks change and its stored instants differ by an hour across a daylight-saving boundary.

A date already taken is skipped, not refused: the answer is `201` with `appointments` for what was booked and `skipped` for the dates that were not, so a course may come back shorter than the rule asked for. Every session shares the chair, practitioner, service, length and patient of the first, and carries the same `seriesId`.

A session is moved, cancelled or deleted on its own afterwards through the ordinary appointment routes. Booking a course sends the patient one email listing every session, with one calendar invitation covering them all.

Body

Example request

{
  "startAt": "2026-07-01T09:00:00.000Z",
  "endAt": "2026-07-01T09:30:00.000Z",
  "chairId": "3f1b8a20-....",
  "patientId": "7d2c9e11-....",
  "practitionerId": "c81a4b33-....",
  "serviceRef": "Physiotherapy session",
  "repeat": { "everyWeeks": 1, "count": 10 }
}

Response · 201

{
  "data": {
    "seriesId": "9b4d2f10-....",
    "appointments": [{ "id": "a7c30e51-....", "startAt": "2026-07-08T09:00:00.000Z" }],
    "skipped": [{ "startAt": "2026-07-15T09:00:00.000Z", "endAt": "2026-07-15T09:30:00.000Z", "reason": "clash" }]
  },
  "requestId": "req_5f2c1e40-...."
}

Errors

POST/api/v1/appointments

Creates an appointment, a reminder, or a chair-blocking unavailable entry.

Any practice member can do this; there is no owner-only gate on appointments, unlike chairs and practice settings.

A chairId or patientId belonging to another practice is rejected as validation_failed, not surfaced as a database error.

Body

Example request

{
  "type": "appointment",
  "startAt": "2026-07-08T10:00:00.000Z",
  "endAt": "2026-07-08T11:00:00.000Z",
  "chairId": "5c2f9b74-....",
  "title": "Checkup"
}

Response · 201

{
  "data": {
    "id": "a7c30e51-....",
    "type": "appointment",
    "startAt": "2026-07-08T10:00:00.000Z",
    "endAt": "2026-07-08T11:00:00.000Z"
  },
  "requestId": "req_5f2c1e40-...."
}

Errors

GET/api/v1/appointments/:appointmentId

Fetches one appointment.

Path parameters

Response · 200

{
  "data": { "id": "a7c30e51-....", "type": "appointment" },
  "requestId": "req_5f2c1e40-...."
}

Errors

PATCH/api/v1/appointments/:appointmentId

Updates an appointment. Every field from the create body except status, all optional.

endAt > startAt is re-checked whenever either changes, against the existing value of the other if only one is sent. The conflict check re-runs against the post-update chair and time range, excluding this appointment from its own check.

`status` is **not** accepted here. Answering a booking request goes through the status endpoint below, so a transition is always checked against the one it is coming from.

Setting `chairId` to null on a booking is refused: a booking occupies a chair by definition. A 409 can also mean the request expired while you were editing it, or the row changed underneath the edit.

Path parameters

Example request

{
  "startAt": "2026-07-08T10:30:00.000Z",
  "endAt": "2026-07-08T11:30:00.000Z"
}

Response · 200

{
  "data": {
    "id": "a7c30e51-....",
    "startAt": "2026-07-08T10:30:00.000Z",
    "endAt": "2026-07-08T11:30:00.000Z"
  },
  "requestId": "req_5f2c1e40-...."
}

Errors

POST/api/v1/appointments/:appointmentId/status

Answers or withdraws a booking request, and cancels a confirmed appointment.

This is the only way a client changes a status, and the transitions are fixed: a `requested` appointment may be confirmed, declined or cancelled (withdrawn), a `confirmed` one may be cancelled, and `declined`, `cancelled` and `expired` are final. Every transition is checked against the status the appointment is coming from, which is why `PATCH` will not take a `status` field. The one status a client never sets is `expired`: the booking-request expiry task sets that on its own.

Confirming re-runs the overlap check, so a request can be refused at the moment of confirmation if the chair or the practitioner filled up while it waited. Confirming without a `chairId` takes the practitioner's usual chair when it is free at that time, otherwise the chair the request already holds. If both are taken it comes back as a 400 `chair_booked` listing the chairs that are still free, so you can pick one and confirm again, and as a 409 `chair_booked` when no chair is free at all.

Sending the status an appointment already has is a no-op `200` returning the row unchanged, so a retried answer is safe. It is a 409 only when the retry also sends a different chair or practitioner, because reporting the first answer's booking as yours would be false.

Path parameters

Body

Response · 200

{
  "data": { "appointment": { "id": "0f1c7a2e-....", "status": "confirmed" } },
  "requestId": "req_5f2c1e40-...."
}

Errors

DELETE/api/v1/appointments/:appointmentId

Deletes an appointment, cancelling any reminder scheduled for it.

Path parameters

Response · 200

{
  "data": { "deleted": true },
  "requestId": "req_5f2c1e40-...."
}

Errors

GET/api/v1/appointments/availability

Computes the free slots on one chair for one calendar day.

Slots are bounded by the practice's working hours and slot length, falling back to defaults for any unset setting. A day the practice is closed returns no slots at all rather than an error.

Busy means an appointment that is `requested` or `confirmed`, an `unavailable` entry on that chair, or practice-wide blocked time. A `declined`, `cancelled` or `expired` appointment does not make a slot busy, and `reminder` entries are ignored entirely because they do not occupy a chair. A slot that has already started is left out, so asking about today returns only what can still be booked.

Query parameters

Response · 200

{
  "data": {
    "slots": [
      { "startAt": "2026-07-08T06:00:00.000Z", "endAt": "2026-07-08T07:00:00.000Z" }
    ]
  },
  "requestId": "req_5f2c1e40-...."
}

Errors