Appointment-services API

Auto-generated from the OpenAPI spec. Run node docs-site/scripts/fetch-openapi.js to regenerate.

GET /api/v1/appointment-services

List Appointment Services

bookable_only=true is an opt-in filter (default false, fully backward-compatible) for booking-flow clients: a service only appears if at least one of its eligible instructors has a genuinely bookable slot within the next 14 days (see instructor_has_bookable_slot). Because that can't be expressed as a single SQL predicate, this path loads all is_active-filtered services unpaginated, filters in Python, then computes total and paginates the filtered set. The default path (bookable_only omitted/false) is unchanged — SQL-level offset/limit pagination, no behavior or performance change, so existing desktop consumers (service CRUD, staff-side booking helpers) keep seeing every active service, including ones with zero assigned instructors yet.

Parameters

Name	In	Required	Type	Description
include_inactive	query	No	boolean
bookable_only	query	No	boolean
page	query	No	integer
page_size	query	No	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---

POST /api/v1/appointment-services

Create Appointment Service

Request body

Field	Required	Type	Description
name	Yes	string
description	No	string
duration_minutes	Yes	integer
buffer_minutes	No	integer
credits_cost	No	integer
establishment_ids	No	array

Responses

• 201 — Successful Response
• 422 — Validation Error

---

GET /api/v1/appointment-services/{service_id}/available-instructors

List Available Instructors For Service

Instructors eligible for this service: at least one active availability window scoped to the service (NULL-service_id windows are wildcards for every service), — when the service is scoped to specific establishments — whose own location matches one of them (a service with no establishment links is open to instructors anywhere), AND who is bookable.

The bookability half depends on date:

• date omitted (default, unchanged): the instructor must have at least one genuinely bookable slot (long-enough window, not already fully booked) within the next 14 days. This does NOT pin down one specific date/day — an instructor can show up here because of a slot on day 12 of the window even though day 1 is fully booked; GET /appointments/available-slots is still what resolves a specific date's slots.
• date passed (YYYY-MM-DD): the 14-day check is replaced by a purely structural one — the instructor must have an active availability window for that specific date's weekday, scoped to this service (or a NULL-service_id wildcard) and long enough for the service duration. No existing-appointment conflict check is done (that is available-slots' job, and create-appointment has its own slot-conflict guard). This supports the desktop "Book Appointment" modal when the date is locked to a calendar-clicked day, which may be fully booked for the next 14 days or even in the past (retroactive booking by full-access managers).

Parameters

Name	In	Required	Type	Description
service_id	path	Yes	integer
date	query	No

Responses

• 200 — Successful Response
• 422 — Validation Error

---

GET /api/v1/appointment-services/{service_id}

Get Appointment Service

Parameters

Name	In	Required	Type	Description
service_id	path	Yes	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---

PATCH /api/v1/appointment-services/{service_id}

Update Appointment Service

Parameters

Name	In	Required	Type	Description
service_id	path	Yes	integer

Request body

Field	Required	Type	Description
name	No	string
description	No	string
duration_minutes	No	integer
buffer_minutes	No	integer
credits_cost	No	integer
is_active	No	boolean
establishment_ids	No	array

Responses

• 200 — Successful Response
• 422 — Validation Error

---

DELETE /api/v1/appointment-services/{service_id}

Deactivate Appointment Service

Soft-delete: deactivate the service (reversible via PATCH is_active=true).

This endpoint never hard-deletes — appointment history referencing the service must be preserved, consistent with the "deactivate = reversible" convention established for membership types. There is no companion hard-delete route for appointment services in this round.

Parameters

Name	In	Required	Type	Description
service_id	path	Yes	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---