Use the API with an AI agent

Updated · 5 min read

Everything your front desk does, an AI agent or a script can do through the API: read your services and the free times, book someone, move or cancel a booking, confirm a held one, write a note. A booking made this way is emailed to the customer like one made on the booking page, unless you say otherwise.

Make a key

  1. Open Integrations, then API keys, and choose New API key.

  2. Give it a Name, like "Booking agent".

  3. Under Scopes, tick only what the agent needs. To book:

    • Read bookings, the free times, the classes and a booking's timeline (bookings:read)
    • Book, move, cancel and confirm bookings (bookings:write)
    • Read services (services:read) and Read staff, their hours and time off (staff:read), to know what to book and with whom.

    An agent that only answers "when are you free?" needs bookings:read and the two reads, never bookings:write.

  4. Choose Create API key and copy the key. It is shown once.

A key acts as the member who made it, and can do only what that member may do. A key made by someone in the Staff group books, moves and cancels only on that person's own time. One made by the Front desk acts on everyone's bookings, but changes no service and no one's hours.

Show the agent the API

Your site describes its whole API for an AI at /llms.txt (for a site at yourstudio.simplest1.com, https://yourstudio.simplest1.com/llms.txt), and for people at /api/docs. Give the agent that address and the key. The key goes in each request:

Authorization: Bearer sk_live_...

Times

Every time the API answers is in UTC (Z) unless the request names a zone with ?tz=, such as ?tz=Europe/Lisbon; each also carries local, its clock time, and zone, the zone that clock is in. A time the agent sends carries its offset (start, such as ...T09:00:00+01:00), or a local clock time with its zone. A clock time without a zone is refused, never guessed. Dates are YYYY-MM-DD.

The calls an agent uses

List the services and the staff, to find their ids:

GET /api/v1/services
GET /api/v1/staff

A session's free times, a week from from unless to says otherwise, each with the staff member it goes to:

GET /api/v1/availability?service={id}&from=YYYY-MM-DD&tz=Europe/Lisbon

Add &staff={id} for one person's times only. These are exactly the times your booking page offers.

A class's dates, each with its places left:

GET /api/v1/classes?service={id}

Book a session's time, or a place on a class's date with class_id instead of start:

POST /api/v1/bookings
{"service_id": "svc_...", "start": "...T09:00:00+01:00",
 "name": "...", "email": "...", "phone": "...",
 "answers": {"{question id}": "..."}}

answers holds the replies to the service's questions by each question's id. If someone took the time a moment before, the booking is refused with 409 time_taken; ask for the three free times nearest it and offer those:

GET /api/v1/availability?service={id}&near=...T09:00:00+01:00

Move a booking, or cancel it with a line for the customer's email:

POST /api/v1/bookings/{id}/actions/reschedule
{"start": "...T11:00:00+01:00"}

POST /api/v1/bookings/{id}/actions/cancel
{"note": "Our therapist is ill today, sorry."}

List the bookings waiting for your confirmation, and confirm or decline one:

GET /api/v1/bookings?view=held
POST /api/v1/bookings/{id}/actions/confirm
POST /api/v1/bookings/{id}/actions/decline

view is also upcoming (the default), past or cancelled; q= finds a booking by the customer's name, email or phone, or its number.

Leave a note for your team on a booking, never emailed:

POST /api/v1/bookings/{id}/timeline
{"kind": "note", "body": "Asked for the room by the window."}

Statuses, kinds and places are ids, like held or video, never words in a language.

The same rules as the booking page

  • Only free times. A booking or a move takes a time only when it is free by the same rules as the page: the hours, time off, closed days, other bookings and the minutes kept free around them, the notice and how far ahead. A time that is not free is 409 time_not_free.
  • One place each. A class's full date is 409 class_full; a customer who already has a place on it, 409 already_booked.
  • Your emails for the day count. Each email to a customer counts against the site's emails for the day. Past them, the booking or the change is still made, and the answer says so in unsent (rate_limited) beside it. Do not send it again: it is done, and only its email was not sent.

Bring your upcoming bookings in

Moving from another tool, send each booking still to come with "notify": false, so your customers are not emailed twice, and with "any_time": true and its staff_id, so it is booked at its time even outside today's hours or over another booking, as your team's own bookings may be:

POST /api/v1/bookings
{"service_id": "svc_...", "staff_id": "stf_...",
 "start": "...T09:00:00+01:00", "name": "...", "email": "...",
 "any_time": true, "notify": false}

What it should never do without being asked

Tell the agent to ask a person first before it:

  • cancels a booking, declines a held one or marks a no-show;
  • books with any_time, over your hours or another booking;
  • sends "notify": false on a real booking, which leaves the customer with no confirmation and no link to move or cancel it;
  • cancels a class's date (POST /api/v1/classes/{id}/actions/cancel), which emails everyone booked on it;
  • changes or deletes a service or a staff member, or anyone's hours.

The simplest guard is the key itself: an agent that only offers times gets no bookings:write, and none gets services:write or staff:write unless it must.

Let the agent hear about changes

Instead of asking every few minutes, add a webhook under Integrations, Webhooks with the events it needs: A booking is made, or a held one confirmed (booking.created), A booking gets a new time (booking.rescheduled), A booking is cancelled, or a held one declined (booking.cancelled), A booking sent with no bot check is held (booking.held). Your site calls the agent's address each time.

Made with Simplest1