What you can do
Read the catalog
Branches, services, and professionals, with the rules that tie them together.
Query availability
Open slots for a given date, a range of dates, or simply the next ones available.
Book
Create an appointment with the customer’s data embedded — no prior customer record needed.
Confirm or cancel
Move an appointment out of
pending, or release the slot.Scopes
A public site that only displays branches, services and open times needs the four
:read scopes and nothing more. Add the appointment scopes only to the token that actually books.
The booking model
A branch is a location. It offers services, each with a duration and its own rules about which professionals can deliver it. Availability is computed from that combination, so a slot is always specific to a service — asking “what is free on Tuesday” without naming a service has no answer. The customer is embedded in the appointment, not referenced. You do not create a customer record first; you pass name, and optionally phone and email, inside the booking. That also means scheduling customers are separate from CRM customers — the two are not linked automatically.Appointments land in pending
Creating an appointment does not confirm it. It lands in pending and stays there until you call confirm explicitly.
That extra step exists so you can build flows where something has to happen in between — a payment clears, a human validates, or the customer confirms from a link. If your flow has none of that, chain create and confirm in the same request handler.
Confirm only accepts an appointment that is currently pending; anything else returns 409.
Ids and time
The appointment_id is a UUID v4 generated by Keebai, not a Mongo ObjectId like the rest of the platform. Branch, service, and professional ids are ObjectIds.
Dates are YYYY-MM-DD and times are HH:mm in the branch’s timezone, not UTC and not the caller’s. If the service defines a duration you can omit end_time and Keebai computes it.
Errors
Branch on
error.code, not on the message text — a 409 on create means the slot is gone, a 409 on confirm means someone already confirmed or cancelled it.
Next steps
List branches
Start from the locations available to your tenant.
Create an appointment
Book a slot with the customer embedded.