cirrux

Scheduling pages API

A scheduling page is a booking link: a meeting of a set length that people book themselves, at a time the page offers and the host is free. Create, change and delete pages, and preview the times a page offers. All endpoints are under https://api.cirrux.co/public_api/v1.

Every endpoint acts on one person’s calendars, so it needs a user-scoped OAuth token. A workspace API key is refused with 403 forbidden. Reading needs calendar.read, and creating, changing or deleting needs calendar.write. You see the pages that book into a calendar you can see, and you can change those that book into a calendar you can add events to.

A page takes bookings as soon as it exists, and every booking sends an invitation from the host’s address. Booked meetings are ordinary events in the host’s calendar, readable through the Calendar API.

The scheduling page object#

FieldTypeRequiredDescription
objectstringnoAlways scheduling_page.
uuidstringnoThe page.
urlstringnoWhere people book: https://book.cirrux.co/s/{slug}.
slugstringnoThe last part of the url.
titlestringnoThe meeting’s name, shown on the page and in the event.
descriptionstring | nullnoShown on the page, when there is one.
locationstring | nullnoWhere the meeting takes place.
duration_minutesnumbernoHow long a booked meeting is.
timezonestringnoThe IANA time zone the page’s weekly hours are read in, like Europe/Amsterdam.
activebooleannoWhether the page takes bookings. A page switched off keeps its url, and its link says it is unavailable until it is switched back on.
hold_timesbooleannoWhether the offered times are blocked in the booking calendar until someone books. See Holding times.
minimum_notice_minutesnumbernoHow far ahead a booking must be made.
booking_window_daysnumbernoHow many days ahead the page offers times.
availabilityobjectnoWhen the page offers time, before anything busy is taken out. See Availability.
hostsarraynoWho is booked, as a list of one host object (below). Pages with several hosts come later.
created_atstringnoWhen it was created.
updated_atstringnoWhen it last changed.
{
  "object": "scheduling_page",
  "uuid": "5e6f7a8b-1111-4c2d-8e3f-000000000001",
  "url": "https://book.cirrux.co/s/intro-call-k3m9x",
  "slug": "intro-call-k3m9x",
  "title": "Intro call",
  "description": "A first chat about your project.",
  "location": null,
  "duration_minutes": 30,
  "timezone": "Europe/Amsterdam",
  "active": true,
  "hold_times": false,
  "minimum_notice_minutes": 240,
  "booking_window_days": 60,
  "availability": {
    "type": "recurring",
    "hours": {
      "monday": [{ "start": "09:00", "end": "17:00" }],
      "wednesday": [{ "start": "13:00", "end": "17:00" }]
    }
  },
  "hosts": [
    {
      "user_uuid": "1a2b3c4d-2222-4e5f-9a1b-000000000002",
      "mailbox_uuid": "1c2d3e4f-3333-4a5b-8c6d-000000000003",
      "booking_calendar_uuid": "9a8b7c6d-4444-4e5f-9a1b-000000000004",
      "availability_calendar_uuids": [
        "9a8b7c6d-4444-4e5f-9a1b-000000000004"
      ]
    }
  ],
  "created_at": "2026-11-16T09:12:44.512Z",
  "updated_at": "2026-11-16T09:12:44.512Z"
}

The host object#

FieldTypeRequiredDescription
user_uuidstringnoThe person who owns the host mailbox.
mailbox_uuidstringnoThe mailbox that organizes booked meetings and sends their invitations.
booking_calendar_uuidstringnoThe calendar booked meetings land in, a calendar_uuid as the Calendar API takes it.
availability_calendar_uuidsstring[]noThe calendars whose events count as busy. Always includes the booking calendar, so a booking blocks its own time.

Availability#

A page has its own availability, which does not follow the host’s working hours once it is created. It is one of three types:

  • recurring: weekly hours in the page’s timezone. hours maps a day name (monday to sunday) to a list of HH:MM ranges. A day left out is off, and at least one range is needed.
  • windows: explicit ranges, each a start and an end date-time with an offset. Meetings are offered anywhere inside them. 1 to 200 windows.
  • slots: explicit start times, each a start date-time with an offset and a meeting long. 1 to 200 slots.
{
  "type": "recurring",
  "hours": {
    "monday": [{ "start": "09:00", "end": "17:00" }],
    "friday": [{ "start": "09:00", "end": "12:00" }]
  }
}
{
  "type": "windows",
  "windows": [
    { "start": "2026-11-24T13:00:00+01:00", "end": "2026-11-24T17:00:00+01:00" }
  ]
}
{
  "type": "slots",
  "slots": [
    { "start": "2026-11-24T13:00:00+01:00" },
    { "start": "2026-11-25T10:00:00+01:00" }
  ]
}

The times a page offers are its availability minus the host’s busy time, from minimum_notice_minutes from now to the end of booking_window_days. An event in one of the host’s availability calendars counts as busy unless it is marked free or the host declined it.

Holding times#

With "hold_times": true, a page with windows or slots blocks the times it offers in the booking calendar with busy events called “Hold”, without guests, so nothing else gets scheduled there while you wait for a booking. The page itself still offers those times. The first booking deletes every hold and switches hold_times off. Holds follow the page: they move when its times or booking calendar change, and go when it is switched off, deleted, or set to "hold_times": false. Weekly hours have no end to hold up to, so a recurring page cannot hold times.

Scheduling pages#

List scheduling pages

GET/v1/scheduling_pages

Returns every scheduling page you can see, oldest first: those that book into a calendar you can see, including pages of a shared mailbox. Not paginated. Scope calendar.read.

curl https://api.cirrux.co/public_api/v1/scheduling_pages \
  -H "Authorization: Bearer $CIRRUX_TOKEN"
{
  "object": "list",
  "url": "/v1/scheduling_pages",
  "has_more": false,
  "data": [
    {
      "object": "scheduling_page",
      "title": "Intro call",
      "url": "https://book.cirrux.co/s/intro-call-k3m9x",
      …
    }
  ]
}

Get a scheduling page

GET/v1/scheduling_pages/{uuid}

Returns one page. A page you cannot see is 404 not_found. Scope calendar.read.

Preview the times a page offers

GET/v1/scheduling_pages/{uuid}/slots

Returns the bookable times between two dates: what the booking page offers anyone with the link right now. A page switched off still previews the times it would offer. Times are written with the page’s UTC offset on that date, and timezone on the list says which zone that is. Not paginated. Scope calendar.read.

FieldTypeRequiredDescription
fromstringnoThe first date, YYYY-MM-DD in the page’s timezone. Defaults to today.
tostringnoThe last date, included. Defaults to 13 days after from, two weeks in all. At most 62 days from from.
curl -G https://api.cirrux.co/public_api/v1/scheduling_pages/5e6f7a8b-…/slots \
  -d from=2026-11-23 -d to=2026-11-27 \
  -H "Authorization: Bearer $CIRRUX_TOKEN"
{
  "object": "list",
  "url": "/v1/scheduling_pages/5e6f7a8b-…/slots",
  "has_more": false,
  "timezone": "Europe/Amsterdam",
  "data": [
    { "start": "2026-11-23T09:00:00+01:00", "end": "2026-11-23T09:30:00+01:00" },
    { "start": "2026-11-23T09:30:00+01:00", "end": "2026-11-23T10:00:00+01:00" },
    …
  ]
}

Create a scheduling page

POST/v1/scheduling_pages

Creates a page and returns 201 with the scheduling page object. It takes bookings straight away unless you send "active": false. Unknown fields are refused with 422 invalid_value rather than ignored. Scope calendar.write.

FieldTypeRequiredDescription
titlestringyesThe meeting’s name, up to 200 characters.
duration_minutesnumberyes5 to 720, a multiple of 5.
slugstringno3 to 64 lowercase letters, digits and dashes, starting and ending with a letter or digit. Defaults to the title with a random ending, like intro-call-k3m9x.
descriptionstring | nullnoUp to 2000 characters.
locationstring | nullnoUp to 500 characters.
timezonestringnoAn IANA time zone. Defaults to the host’s own.
availabilityobjectnoSee Availability. Defaults to the host’s working hours, or Monday to Friday 09:00 to 17:00 when they have none.
minimum_notice_minutesnumberno0 to 43200 (30 days). Defaults to 240.
booking_window_daysnumberno1 to 365. Defaults to 60.
activebooleannoDefaults to true.
hold_timesbooleannoDefaults to false. Needs windows or slots availability.
hostsarraynoExactly one host, every field optional: mailbox_uuid, booking_calendar_uuid and availability_calendar_uuids (1 to 50). Left out, the mailbox is the booking calendar’s, or else your own; the booking calendar is that mailbox’s default calendar; and the availability calendars are every calendar its owner owns that you can see. The mailbox can be a shared one, as long as you can add events to the booking calendar.
curl https://api.cirrux.co/public_api/v1/scheduling_pages \
  -H "Authorization: Bearer $CIRRUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Intro call",
    "duration_minutes": 30,
    "availability": {
      "type": "recurring",
      "hours": {
        "tuesday": [{ "start": "10:00", "end": "12:00" }],
        "thursday": [{ "start": "14:00", "end": "17:00" }]
      }
    }
  }'

Change a scheduling page

POST/v1/scheduling_pages/{uuid}

Changes the fields you send, with the same rules as on create, and returns the page. Switch a page off and on with active. In hosts, what you leave out stays as it is: a new booking_calendar_uuid keeps the availability calendars, and the other way round. Moving the page to another mailbox takes that mailbox’s defaults for whatever you leave out. Changing the slug changes the url, and the old link stops working. Scope calendar.write.

curl https://api.cirrux.co/public_api/v1/scheduling_pages/5e6f7a8b-… \
  -H "Authorization: Bearer $CIRRUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Delete a scheduling page

DELETE/v1/scheduling_pages/{uuid}

Deletes a page and returns 204. Its link stops working and its holds are removed. Meetings already booked stay in the calendar. Scope calendar.write.

Errors#

Scheduling page error codes

On top of the shared errors, scheduling page endpoints can return:

StatuserrorWhen
404not_foundThe page does not exist or books into no calendar you can see.
403forbiddenYou can see the page but not change it: that takes write access to the calendar it books into.
402subscription_requiredThe host mailbox’s workspace needs an active subscription to take bookings. Checked on create and whenever the host changes.
409slug_takenAnother page uses that slug.
422invalid_valueA field breaks a rule above, or is unknown. Also a host mailbox or calendar you cannot use, hold_times on weekly hours, or a slots preview with dates it cannot read, to before from, or more than 62 days. The error_description names the field.
422invalid_uuidThe page uuid in the path is not a valid UUID.