---
title: "How Agenda works"
description: "Agenda's scheduling model, from services and resources to availability, and how appointments, bookings and the waitlist fit together."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Agenda works

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](/api/agenda/). 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](/en/developers/agenda/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](/en/developers/agenda/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`](/api/agenda/bookings/lookup/) | Any, by date range, patient, agenda or status: [`agenda.appointments.list`](/api/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`](/api/agenda/booking-offerings/list/), [`agenda.bookingLocations.list`](/api/agenda/booking-locations/list/), [`agenda.bookingRequirements.get`](/api/agenda/booking-requirements/get/), [`agenda.nearestBookingSlots.list`](/api/agenda/nearest-booking-slots/list/), [`agenda.bookingSlots.list`](/api/agenda/booking-slots/list/), [`agenda.bookings.create`](/api/agenda/bookings/create/), [`agenda.bookings.get`](/api/agenda/bookings/get/), [`agenda.bookings.reschedule`](/api/agenda/bookings/reschedule/) and [`agenda.bookings.cancel`](/api/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`](/api/agenda/appointments/get/) and [`agenda.appointments.list`](/api/agenda/appointments/list/) read any appointment of the organization. [`agenda.appointments.create`](/api/agenda/appointments/create/), [`agenda.appointments.reschedule`](/api/agenda/appointments/reschedule/) and [`agenda.appointments.changeStatus`](/api/agenda/appointments/change-status/) accept only a signed-in person, not API keys or machine tokens, and aren't offered on [MCP](/en/developers/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](/en/developers/agenda/catalog/).

## 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`](/api/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`](/api/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`](/api/agenda/first-availability/get/) and [`agenda.availability.list`](/api/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`](/api/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](/en/developers/authentication/#scopes).

## Next steps

- **Availability and booking** — Find slots, check requirements, and book, reschedule or cancel.
- **Catalog** — Services, offerings, resources, locations and schedule rules.
- **Book an appointment** — The whole booking flow with curl.
- **Handle errors and retries** — A booking that timed out, a version conflict, a 429.

Source: https://docs.getarbol.com/en/developers/agenda/index.mdx