Catalog

Agenda’s catalog is how the clinic is set up: the services it offers, the offerings that make each one bookable, the resources that provide them, the sites where they are, and the hours each resource works. Availability is computed from it, so a change here changes the times patients can book.

Who can read and change it

Reading the catalog is open to people and machines holding the :read scope of what they list, such as agenda:services:read; a list accepts no other scope. Changing it accepts only people: a signed-in member whose roles grant the :write scope, such as agenda:services:write, typically through a staff tool. API keys and machine tokens can’t change the catalog.

The lists of services, offerings, resources and locations answer a page at a time, 25 items by default and up to 100: see Pagination. Creating isn’t idempotent, so after a create whose outcome is unknown, list before you create again. There’s no delete operation: set a record’s status to inactive to stop using it. The booking operations offer only active offerings.

Services

A service is what a patient asks for, under the clinic’s name for it, such as a neurology consultation. agenda.services.list filters by status.

Offerings

An offering attaches a service to an agenda, with what it takes to book it. agenda.offerings.list filters by serviceId and status.

Each requirement names a kind of resource and a quantity, 1 by default. alternatives lists the resources that can fill it; when it’s empty, any resource of that kind can. required, true by default, says whether the requirement must be met for the booking to go ahead. In an update, resourceRequirements replaces the whole list for future bookings; existing appointments keep their resources.

An example body for agenda.offerings.create, a 30-minute consultation with one named professional and any room:

{
  "serviceId": "svc_00000000-0000-4000-8000-000000000001",
  "name": "Neurology consultation, Dr. Example",
  "durationMinutes": 30,
  "slotIntervalMinutes": 30,
  "minNoticeMinutes": 120,
  "resourceRequirements": [
    { "kind": "practitioner", "alternatives": ["srs_00000000-0000-4000-8000-000000000003"] },
    { "kind": "room" }
  ]
}

Resources

A resource is anything with its own calendar that a booking uses. agenda.resources.list filters by kind and status.

Locations

Locations are the clinic’s sites, each with its name, address, city, timezone and status. The API reads them, with agenda.locations.list (agenda:locations:read), or with agenda.bookingLocations.list when you book (agenda:bookings:read). It has no operation that creates or changes a location.

Schedule rules

Schedule rules say when a resource works. Each rule is a band of local time, from from to to in HH:MM, read in the resource’s time zone:

• agenda.scheduleRules.list filters by resourceId and answers the complete list, without pages. Each rule has its id, its resourceId and its version.
• agenda.scheduleRules.create adds one rule with resourceId, kind, timezone, from and to.
• agenda.scheduleRules.update changes a rule identified by scheduleRuleId; send its expectedVersion. An update without it is refused with SCHEDULE_RULE_EXPECTED_VERSION_REQUIRED.
• agenda.resourceSchedules.update replaces the resource’s whole schedule at once: rules is the new set, up to 400 rules, and expectedRules holds the id and version of every rule you loaded. If the schedule changed since, the replacement is refused and nothing changes.

An example body for agenda.resourceSchedules.update: Monday to Friday, 07:00 to 12:00 and 14:00 to 17:00, replacing one rule loaded at version 3:

{
  "expectedRules": [{ "id": "sch_00000000-0000-4000-8000-000000000006", "version": 3 }],
  "rules": [
    { "kind": "weekly", "weekdays": [1, 2, 3, 4, 5], "from": "07:00", "to": "12:00" },
    { "kind": "weekly", "weekdays": [1, 2, 3, 4, 5], "from": "14:00", "to": "17:00" }
  ]
}

Versions

Every catalog record has a version. An update requires the version you read as expectedVersion, and is refused with 409 when someone changed the record since:

Read the record again, apply your change to what you read, and send it with the new version. See Handle errors and retries.