Introduction

Bookings API

Overview

Organisation-scoped appointments and reservations (Cloudflare Worker + D1).

Integration guide: Bookings service docs

OpenAPI v0.1.0 · source openapi/bookings.json

OpenAPI 3.0.0 · v0.1.0 · 12 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/health"

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/health"

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Bookings

Appointments and reservations.

get/v1/bookings

List bookings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings"

Lists bookings for the organisation in the JWT (`orgId`) only. Returns summary rows without `details`; use GET `/v1/bookings/{id}` for full scheduling metadata.

Operation ID: listBookings

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
customer_id	query	string (uuid)	Filter by customer UUID within the JWT organisation.
subject_id	query	string (uuid)	Filter bookings that include this subject UUID in `details.subject_ids`.
job_id	query	string (uuid)	—
booking_type	query	string	—
status	query	string	—
statuses	query	string	—
start_after	query	string	—
start_before	query	string	—
q	query	string	Case-insensitive substring search across booking id, number, customer, status, type, and notes.

Responses

200
Bookings
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/bookings

Create booking

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings"

Creates a booking for the JWT organisation. Required: `customer_id` and `start_at`. Put cross-service references and scheduling extras in optional `details` (opaque UUIDs only).

Operation ID: createBooking

Request body(required)

application/jsonBookingCreate

Responses

201
Booking created
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/bookings/{id}

Get booking

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/example-id"

Returns a booking in the JWT organisation. Another org's id returns 404.

Operation ID: getBooking

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Booking id (UUID).

Responses

200
Booking
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

patch/v1/bookings/{id}

Update booking

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/example-id"

Operation ID: updateBooking

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Booking id (UUID).

Request body(required)

application/jsonBookingPatch

Responses

200
Booking updated
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/bookings/search

Search bookings

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/search"

Same filters and pagination as GET `/v1/bookings`, including optional `q` text search. Returns summary rows without `details`.

Operation ID: searchBookings

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
customer_id	query	string (uuid)	Filter by customer UUID within the JWT organisation.
subject_id	query	string (uuid)	Filter bookings that include this subject UUID in `details.subject_ids`.
job_id	query	string (uuid)	—
booking_type	query	string	—
status	query	string	—
statuses	query	string	—
start_after	query	string	—
start_before	query	string	—
q	query	string	Case-insensitive substring search across booking id, number, customer, status, type, and notes.

Responses

200
Bookings
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/bookings/{id}/assign

Assign staff to booking

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/example-id/assign"

Sets or clears an optional staff assignee. Bookings are created without an assignee; use this when you want `details.assigned_user_id` on reads. Send `assigned_user_id: null` to unassign. Not allowed when the booking is cancelled (422).

Operation ID: assignBooking

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Booking id (UUID).

Request body(required)

application/jsonBookingAssign

Responses

200
Booking after assignment
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/bookings/{id}/cancel

Cancel booking

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/example-id/cancel"

Operation ID: cancelBooking

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Booking id (UUID).

Responses

200
Booking cancelled
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/bookings/{id}/start

Start booking

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/example-id/start"

Operation ID: startBooking

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Booking id (UUID).

Responses

200
Booking started
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/bookings/{id}/complete

Complete booking

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/bookings/example-id/complete"

Operation ID: completeBooking

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Booking id (UUID).

Responses

200
Booking completed
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Audit

Immutable change log for this service.

get/v1/audit

Audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/bookings/v1/audit"

Lists audit events for the organisation in the JWT (`orgId`).

Operation ID: listAudit

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Audit events
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json