# Bookr developer API — the full contract, in plain text

This file is generated from the same operation registry that runs the API, so it is the truth.
Version 1.0.0. Human docs: https://mybookr.app/developers · OpenAPI: https://mybookr.app/openapi.json

## The three ways in
1. THE EMBED — one <script> tag puts the live booking page in a site. Instructions under "Embedding Bookr on your own website" in https://mybookr.app/llms.txt. The customer pays INSIDE Bookr's frame; never build your own checkout.
2. THE REST API — base URL https://mybookr.app/api/v1, header `Authorization: Bearer bk_live_…`. Keys are made in the app (Business → Connect your AI) or at https://mybookr.app/developer. Every plan.
3. MCP — https://mybookr.app/mcp (Streamable HTTP, stateless), same header. Tools = the operations below, named with underscores (bookings.cancel → bookings_cancel), filtered to the key's scopes.

## Scopes
- read:catalog
- read:bookings
- read:customers
- read:messages
- read:reviews
- read:insights
- write:catalog
- write:bookings
- write:customers
- write:messages
- write:reviews
- write:staff
- write:business
- `read` (legacy keys only) = read:catalog + read:bookings, never a write.
A key with read:customers or any write scope must never be placed in a public website. Only read:catalog / read:bookings keys belong in page source.

## Conventions
- JSON in and out. Times ISO 8601 (UTC in, UTC out; the business timezone is on /business). Prices in pence. Ids are UUIDs.
- GET options in the query string; POST/PATCH/PUT/DELETE take a JSON body. `*` below marks a required field.
- Errors: 400 bad input · 401 bad key · 402 plan without API access (no current plan) · 403 missing scope or not this business's record · 404 · 409 slot taken/blocked · 422 refused by a business rule (message is safe to show) · 429 rate limited (120/min per IP unauthenticated, 600/min per key).
- /availability returns BUSY ranges. /slots returns FREE start times for one service on one date, computed with the booking page's rules.
- Hand a chosen slot to Bookr to confirm and pay: window.Bookr.open({ service, start }) on a page with the embed, or https://mybookr.app/HANDLE?service=SERVICE-ID&start=ISO. If the slot is free the customer lands on the details step; otherwise the calendar shows.
- Nothing here takes a card payment. POST /bookings creates an UNPAID confirmed booking, like an owner adding one by hand.
- A complete working example (a barbershop's own site: read-only key for services + free slots, the embed, and Bookr.open at a chosen slot): https://bookr-demo-site.vercel.app — source https://github.com/resellrealm/client-templates/tree/main/demo-site

## Operations
### GET /me  —  me  (any key)
The key's name, scopes, business and plan. Use it to check a key works.

### GET /business  —  business_get  (scope: read:catalog)
Public profile, booking rules (notice, horizon, cancellation window), timezone and format. works_at says where the business works: premises (address and map shown to customers), mobile (customers see the town only and give THEIR address when booking) or both. address/postcode are the owner's own record and are never shown to customers for a mobile business.

### PATCH /business  —  business_update  (scope: write:business)
The words and arrangement on the booking page: description (about), announcement, arrival_instructions, confirmation_note, faqs, amenities (badge keys), page_layout, social_links, service_area. Plan gates apply on the page as they do in the app. Nothing here touches money, hours or the address.
- description (body, string): About (≤280)
- announcement (body, string): Notice at the top (≤140)
- arrival_instructions (body, string): Before they arrive
- confirmation_note (body, string): Added to confirmation emails (≤300)
- faqs (body, array): [{q, a}]
- amenities (body, array): Badge keys, e.g. ["pet_friendly","student_discount"]
- page_layout (body, object): { order: [...], hidden: [...] } over the optional sections
- social_links (body, object): { instagram, tiktok, facebook, x, website, whatsapp, google }
- service_area (body, string): Area a mobile business covers (≤60)

### GET /services  —  services_list  (scope: read:catalog)
Every service, active and inactive, with price in pence and duration in minutes.
- active (query, boolean): Only active (bookable) services

### POST /services  —  services_create  (scope: write:catalog)
Add a bookable service. Price is in pence; duration in minutes (5–480). Plan service limits apply.
- name* (body, string): Name, up to 80 characters
- price_pence* (body, integer): Price in pence: at least 500 (£5), or 0 for a free service
- duration_min* (body, integer): Duration in minutes
- description (body, string): Up to 300 characters
- buffer_min (body, integer): Gap after the appointment, minutes
- active (body, boolean): Bookable now (default true)

### GET /services/{id}  —  services_get  (scope: read:catalog)
One service by id.
- id* (path, string/uuid): Record id

### PATCH /services/{id}  —  services_update  (scope: write:catalog)
Change name, price, duration, description, buffer or active.
- id* (path, string/uuid): Record id
- name (body, string): Up to 80 characters
- price_pence (body, integer): Pence
- duration_min (body, integer): Minutes
- description (body, string): Up to 300 characters
- buffer_min (body, integer): Minutes
- active (body, boolean): Bookable

### DELETE /services/{id}  —  services_deactivate  (scope: write:catalog)
Hides it from the booking page. Existing bookings keep it. Nothing is deleted — the same as the app.
- id* (path, string/uuid): Record id

### GET /hours  —  hours_get  (scope: read:catalog)
Seven rows, day_of_week 0 = Sunday. Times are HH:MM in the business timezone.

### PUT /hours  —  hours_set  (scope: write:catalog)
Upsert any subset of days. Each item: day_of_week (0–6, 0 = Sunday), is_open, open_time, close_time (HH:MM).
- hours* (body, array): Array of {day_of_week, is_open, open_time, close_time}

### GET /staff  —  staff_list  (scope: read:catalog)
Team members who can be booked. Pass staff_id to slots and bookings.create to book one of them.

### POST /staff  —  staff_create  (scope: write:staff)
Creates a staff member customers can pick. Plan staff caps are enforced by the database (409 when full). Optionally assign services.
- name* (body, string): Display name
- role (body, string): Role or title shown on the page
- service_ids (body, array): Services this person offers (uuids)

### GET /locations  —  locations_list  (scope: read:catalog)
Branches, for multi-location businesses.

### GET /availability  —  availability_busy  (scope: read:catalog)
BUSY time ranges from now for `days` days (bookings, blocks, time off, holiday, horizon). For free times use slots.
- days (query, integer): 1–90, default 30
- staff_id (query, string/uuid): One team member

### GET /slots  —  slots_list  (scope: read:catalog)
Free start times for a service on one date, computed with the booking page's own rules (hours, duration, notice, horizon, busy ranges). `starts_at` are the same times as ISO instants — pass one to bookings.create, or open the booking frame at it with Bookr.open({service, start}).
- service_id* (query, string/uuid): Service to book
- date* (query, string/date): YYYY-MM-DD in the business timezone
- staff_id (query, string/uuid): One team member

### GET /bookings  —  bookings_list  (scope: read:bookings)
Bookings in a window (default: from now, 30 days). Customer details need read:customers.
- from (query, string/date-time): ISO start (default now)
- to (query, string/date-time): ISO end (default from + 30 days)
- status (query, string): confirmed | pending | completed | cancelled | no_show
- limit (query, integer): 1–500, default 200

### POST /bookings  —  bookings_create  (scope: write:bookings)
Adds a confirmed booking the way the owner does by hand in the app: no card is taken. 409 when the business is at capacity for that time (an appointment business's capacity is its number of active staff), the named staff member is already booked, or the time is blocked. end_at defaults to start_at + service duration; total_pence to the service price.
- service_id* (body, string/uuid): Service
- start_at* (body, string/date-time): ISO start
- customer_address (body, string): Where the business goes. REQUIRED when the business works_at is mobile, or the service is marked is_mobile; ignored otherwise.
- end_at (body, string/date-time): ISO end (default start + duration)
- customer_name (body, string): Customer name
- customer_email (body, string/email): Customer email (confirmation goes here)
- customer_phone (body, string): Customer phone
- notes (body, string): Note from the customer
- staff_id (body, string/uuid): Team member
- total_pence (body, integer): Override price in pence
- party_size (body, integer): For businesses that book by party

### GET /bookings/{id}  —  bookings_get  (scope: read:bookings)
One booking by id.
- id* (path, string/uuid): Record id

### POST /bookings/{id}/cancel  —  bookings_cancel  (scope: write:bookings)
Cancels as the business. A paid booking is refunded by Bookr's normal rules; the customer is told.
- id* (path, string/uuid): Record id
- reason (body, string): Why (shown to the customer)

### POST /bookings/{id}/reschedule  —  bookings_reschedule  (scope: write:bookings)
Move it to a new start (end defaults to keep the same length). The new slot must be free.
- id* (path, string/uuid): Record id
- start_at* (body, string/date-time): New ISO start
- end_at (body, string/date-time): New ISO end

### POST /bookings/{id}/no-show  —  bookings_no_show  (scope: write:bookings)
The customer did not turn up. Applies the business's no-show fee rule if one is set.
- id* (path, string/uuid): Record id

### POST /bookings/{id}/arrived  —  bookings_arrived  (scope: write:bookings)
Check the customer in (or undo with arrived=false).
- id* (path, string/uuid): Record id
- arrived (body, boolean): Default true

### POST /bookings/{id}/undo  —  bookings_undo  (scope: write:bookings)
Puts a completed or no-show booking back to confirmed.
- id* (path, string/uuid): Record id

### GET /blocks  —  blocks_list  (scope: read:bookings)
Owner-blocked time (lunch, admin, days off) from now.
- days (query, integer): 1–365, default 60

### POST /blocks  —  blocks_create  (scope: write:catalog)
Make a range unbookable.
- start_at* (body, string/date-time): ISO start
- end_at* (body, string/date-time): ISO end
- reason (body, string): Shown only to the owner

### PATCH /blocks/{id}  —  blocks_update  (scope: write:catalog)
Move or rename a time block.
- id* (path, string/uuid): Record id
- start_at* (body, string/date-time): ISO start
- end_at* (body, string/date-time): ISO end
- reason (body, string): Owner note

### DELETE /blocks/{id}  —  blocks_delete  (scope: write:catalog)
The time becomes bookable again.
- id* (path, string/uuid): Record id

### GET /customers  —  customers_list  (scope: read:customers)
Everyone who has booked here or is on the client list: visit counts, first and last visit, lifetime spend, blocked flag, private notes. Optional q filters by name, email or phone.
- q (query, string): Search text
- limit (query, integer): 1–1000, default 200

### GET /customers/{id}  —  customers_get  (scope: read:customers)
One customer with the owner's private notes and their bookings at this business.
- id* (path, string/uuid): Record id

### PATCH /customers/{id}  —  customers_update  (scope: write:customers)
Set the owner's private notes, or block / unblock them from booking.
- id* (path, string/uuid): Record id
- notes (body, string): Private notes (owner only)
- blocked (body, boolean): Block from booking

### GET /walkins  —  walkins_list  (scope: read:bookings)
Who is waiting right now (walk-in businesses). Names need read:customers.

### POST /walkins  —  walkins_add  (scope: write:bookings)
Join someone to the queue at the counter.
- customer_name* (body, string): Name
- customer_phone (body, string): Phone
- customer_email (body, string/email): Email
- service_id (body, string/uuid): Service

### PATCH /walkins/{id}  —  walkins_update  (scope: write:bookings)
Correct the name or phone of someone in the queue.
- id* (path, string/uuid): Record id
- name* (body, string): Name
- phone (body, string): Phone

### GET /messages  —  messages_list  (scope: read:messages)
The business's message threads with customers, newest first: every message carries its booking id, who sent it (business or customer) and when. Filter by booking_id for one thread.
- booking_id (query, string/uuid): One booking's thread
- limit (query, integer): Max rows (default 100)

### POST /messages  —  messages_send  (scope: write:messages)
Replies to a customer on one booking, as the business. Bookr delivers it (email and, where enabled, push) and applies the daily cap the app has.
- booking_id* (body, string/uuid): The booking whose customer to message
- body* (body, string): The message (≤2000 chars)

### GET /reviews  —  reviews_list  (scope: read:reviews)
Every review of the business with its rating, text, the owner's reply and dates. Hidden reviews are included with hidden_at set.
- limit (query, integer): Max rows (default 100)

### POST /reviews/{id}/reply  —  reviews_reply  (scope: write:reviews)
Sets or replaces the owner's public reply on a review. Shown on the booking page under the review.
- id* (path, string/uuid): Record id
- reply* (body, string): The reply (≤1000 chars)

### PATCH /staff/{id}  —  staff_update  (scope: write:staff)
Name, role, active flag, and which services they offer.
- id* (path, string/uuid): Record id
- name (body, string): Display name
- role (body, string): Role or title
- active (body, boolean): Shown to customers
- service_ids (body, array): Replace their services (uuids)

### DELETE /staff/{id}  —  staff_remove  (scope: write:staff)
Removes them from the page and the rota. Their past bookings keep their name.
- id* (path, string/uuid): Record id

### GET /insights  —  insights_summary  (scope: read:insights)
Revenue for a period from completed and confirmed bookings (pence), booking counts by status, and the payout ledger totals: paid out, and held/still to come.
- from (query, string/date-time): Start (ISO). Default: 30 days ago
- to (query, string/date-time): End (ISO). Default: now

### POST /business/availability  —  business_availability  (scope: write:business)
The same switch as the app's "Taking bookings". taking_bookings=false stops every booking path (waitlists stay open). Give a message customers will read and, optionally, back_on (ISO date) so it resumes by itself. taking_bookings=true clears both.
- taking_bookings* (body, boolean): true = on, false = off
- message (body, string): What customers read while off (≤160)
- back_on (body, string/date-time): When bookings resume (off until then; resumes automatically)

## Terms
https://mybookr.app/api-terms · Contact: support@mybookr.app