Everything a client can do on the booking page, an agent can do over HTTP: read services, find free times, book and cancel. Same rules, same database — no shortcuts.
Reading a business, its services and its availability needs nothing — it is already public on the booking page. Booking needs no key either, but hands back a `manage_token`. That token is the only way back to the booking, so keep it.
Every booking goes through the same function the booking page uses. Opening hours, absence, minimum notice and the booking window are all checked again inside the transaction that writes. A slot that was free a moment ago may still be refused with `slot_taken` — that is the system working.
| GET | /businesses/{slug} | The business and its booking rules |
| GET | /businesses/{slug}/services | What can be booked |
| GET | /businesses/{slug}/staff | Who works there, and what they do |
| GET | /businesses/{slug}/availability | Free slots for a service |
| POST | /businesses/{slug}/bookings | Make a booking |
| GET | /bookings/{manage_token} | Read a booking |
| POST | /bookings/{manage_token}/cancel | Cancel a booking |
Find a free time and book it. Swap the slug for the business's own.
# 1. What does this shop do?
curl https://www.clientlyapp.com/api/v1/businesses/studionord/services
# 2. When is it free?
curl "https://www.clientlyapp.com/api/v1/businesses/studionord/availability\
?service_id=SERVICE_ID&days=7"
# 3. Book the first free slot. Omit staff_id to let the shop
# assign whoever has the fewest bookings that day.
curl -X POST https://www.clientlyapp.com/api/v1/businesses/studionord/bookings \
-H "Content-Type: application/json" \
-d '{
"service_id": "SERVICE_ID",
"starts_at": "2026-11-25T13:00:00.000Z",
"name": "Ola Nordmann",
"email": "ola@example.no"
}'
# Keep the manage_token from the response: it is the only
# way back to the booking.
curl https://www.clientlyapp.com/api/v1/bookings/MANAGE_TOKEN| validation_failed | 400 | The request body or query was not valid. |
| not_found | 404 | No such business, service or booking. |
| bookings_closed | 409 | This business is not taking online bookings. |
| slot_taken | 409 | That time is no longer free. |
| outside_booking_window | 409 | That time is further ahead than this business accepts. |
| below_minimum_notice | 409 | That time is sooner than this business accepts. |
| staff_unavailable | 409 | That person is not available then. |
| service_not_offered_by_staff | 409 | That person does not perform this service. |
| past_cutoff | 409 | This booking can no longer be cancelled online. Contact the business. |
| booking_state_final | 409 | This booking has already been cancelled, completed or marked as a no-show. |
| rate_limited | 429 | Too many requests. Slow down and try again. |
| internal_error | 500 | Something went wrong on our side. |
Per IP address: reads are generous, bookings are 5 an hour per business. A refusal is 429 with a Retry-After header.
OpenAPI 3.1, generated from the same error table the endpoints answer with — so the documentation cannot drift away from the behaviour.
Open openapi.json