Agenda is Arbol’s scheduling product: the clinic’s calendar. It knows what the clinic offers, who and what provides it, where and at what hours, and which appointments are already booked. From that it works out the times a patient can book, and it keeps a waiting list for the patients it can’t place yet. Each organization has one Agenda.
Everything Agenda does is in the API under https://api.getarbol.com/v1/agenda/, operation by operation in the Agenda API reference. Each operation’s page there shows its Scope, its Credentials and its Effect.
The scheduling model
The clinic sets up a catalog once and keeps it current. See Catalog for how to read and change it.
| Concept | What it is | Ids |
|---|---|---|
| Service | What a patient asks for, such as a neurology consultation or an EEG, with a default duration. | svc_… |
| Offering | A service attached to an agenda: the appointment’s duration, the spacing of start times, the notice and booking horizon, and the resources each appointment needs. | off_… |
| Resource | Anything with its own calendar: a professional, a room, equipment and other kinds. Each has a capacity and a time zone, and can belong to a site. | srs_… |
| Location | A clinic site (sede), with its address, city and time zone. | loc_… |
| Schedule rule | When a resource works: weekly hours, a dated change, time off or a block, in the resource’s local time. | sch_… |
A resource’s kind is practitioner, assistant, room, chair, equipment, location, team or generic. The API’s field descriptions often call a resource an agenda: an offering’s agendas and a slot’s resourceIds are resources.
Availability
Agenda computes free times when you ask for them. For an offering, it reads the schedule rules of the resources the offering needs and the capacity they have left, and answers bookable times, earliest first. Each one is a slot:
| Field | Meaning |
|---|---|
startsAt, endsAt |
The visible appointment, with an explicit time zone offset. |
timezone |
The IANA time zone used for local dates and working hours, such as America/Bogota. |
offeringId, resourceIds |
The offering, and the resources the appointment would use. |
slotToken |
A signed token for that exact time. Booking takes it unchanged. |
A slot isn’t held for anyone: until it’s booked, another booking can take it. See Availability and booking.
Appointments and bookings
An appointment is a booked time for a patient on one or more resources, with an id such as eng_… and a status. The API reaches appointments through two sets of operations, made for different callers. Both work on the same records: an appointment booked through one is read through the other with the same id.
| Bookings | Appointments | |
|---|---|---|
| Made for | Booking on a patient’s behalf: an AI agent, a patient-facing app, another system. | The clinic’s own calendar: staff tools, and systems that read or report on it. |
| Callers | People and machines (API keys and client credentials). | Reads: people and machines. Creating, rescheduling and setting the status: people only. |
| Scopes | agenda:bookings:read, agenda:bookings:write |
agenda:appointments:read, agenda:appointments:write |
| Finding appointments | A patient’s, by document number: agenda.bookings.lookup |
Any, by date range, patient, agenda or status: agenda.appointments.list |
| Writes | Book, reschedule within the same service, cancel with a reason | Create, reschedule, change the status |
| What booking and rescheduling answer | The appointment, with guidance for the patient and a printable slip | The appointment |
Bookings cover the whole path to a booked appointment: agenda.bookingOfferings.list, agenda.bookingLocations.list, agenda.bookingRequirements.get, agenda.nearestBookingSlots.list, agenda.bookingSlots.list, agenda.bookings.create, agenda.bookings.get, agenda.bookings.reschedule and agenda.bookings.cancel. They carry the clinic’s rules for booking for a patient: the intake it requires, payers whose patients only the clinic’s team books, and services with an age rule.
Appointments are the desk’s view. agenda.appointments.get and agenda.appointments.list read any appointment of the organization. agenda.appointments.create, agenda.appointments.reschedule and agenda.appointments.changeStatus accept only a signed-in person, not API keys or machine tokens, and aren’t offered on MCP. Creating requires an idempotencyKey; rescheduling and setting the status require the expectedVersion you read.
Building for patients or with an API key, use bookings. Building a tool where clinic staff sign in, use appointments and the catalog operations.
The waitlist
When no time suits the patient, or only the clinic’s team may book them, Agenda keeps a waiting list for the team to act on. agenda.waitlist.join adds a patient, with their consent, for a service, optionally a professional (resourceId) and their preferred dates. It never books: tell the patient the clinic’s team will contact them. Each entry has a reason:
reason |
When |
|---|---|
manual |
No suitable time was available and the patient agreed to wait. |
payer_review |
The patient’s payer has the booking policy staff_only: the team coordinates and books. |
priority |
The patient asked for an urgent appointment: pass the booked appointment as appointmentId so the team can bring it forward. |
An entry’s status is waiting, offered, booked, expired or cancelled, and its priority is normal or urgent. Joining again for the same patient, service and reason returns the same open entry. agenda.waitlist.list lists the entries: open ones first, urgent and then the longest waiting, then closed ones.
Scopes
| Scope | What it allows |
|---|---|
agenda:bookings:read |
Find bookable services, their requirements and slots, and a patient’s appointments. |
agenda:bookings:write |
Book, reschedule and cancel through the booking operations, and every booking read. |
agenda:availability:read |
Find slots with agenda.firstAvailability.get and agenda.availability.list. |
agenda:appointments:read, agenda:appointments:write |
Read appointments. The write scope also reads, and lets a person create, reschedule and set their status. |
agenda:services:…, agenda:offerings:…, agenda:resources:…, agenda:schedule-rules:… |
:read lists the catalog; :write lets a person change it. A catalog list accepts only its :read scope. |
agenda:locations:read |
List the sites with agenda.locations.list. |
agenda:waitlist:read, agenda:waitlist:write |
Read the waitlist. The write scope also reads, and adds patients to it. |
An API key carries the scopes chosen when it was created; a person’s token counts a scope only as far as their roles grant it. See Authentication.