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#
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always scheduling_page. |
| uuid | string | no | The page. |
| url | string | no | Where people book: https://book.cirrux.co/s/{slug}. |
| slug | string | no | The last part of the url. |
| title | string | no | The meeting’s name, shown on the page and in the event. |
| description | string | null | no | Shown on the page, when there is one. |
| location | string | null | no | Where the meeting takes place. |
| duration_minutes | number | no | How long a booked meeting is. |
| timezone | string | no | The IANA time zone the page’s weekly hours are read in, like Europe/Amsterdam. |
| active | boolean | no | Whether 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_times | boolean | no | Whether the offered times are blocked in the booking calendar until someone books. See Holding times. |
| minimum_notice_minutes | number | no | How far ahead a booking must be made. |
| booking_window_days | number | no | How many days ahead the page offers times. |
| availability | object | no | When the page offers time, before anything busy is taken out. See Availability. |
| hosts | array | no | Who is booked, as a list of one host object (below). Pages with several hosts come later. |
| created_at | string | no | When it was created. |
| updated_at | string | no | When 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#
| Field | Type | Required | Description |
|---|---|---|---|
| user_uuid | string | no | The person who owns the host mailbox. |
| mailbox_uuid | string | no | The mailbox that organizes booked meetings and sends their invitations. |
| booking_calendar_uuid | string | no | The calendar booked meetings land in, a calendar_uuid as the Calendar API takes it. |
| availability_calendar_uuids | string[] | no | The 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’stimezone.hoursmaps a day name (mondaytosunday) to a list ofHH:MMranges. A day left out is off, and at least one range is needed.windows: explicit ranges, each astartand anenddate-time with an offset. Meetings are offered anywhere inside them. 1 to 200 windows.slots: explicit start times, each astartdate-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
/v1/scheduling_pagesReturns 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
/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
/v1/scheduling_pages/{uuid}/slotsReturns 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.
| Field | Type | Required | Description |
|---|---|---|---|
| from | string | no | The first date, YYYY-MM-DD in the page’s timezone. Defaults to today. |
| to | string | no | The 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
/v1/scheduling_pagesCreates 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.
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | yes | The meeting’s name, up to 200 characters. |
| duration_minutes | number | yes | 5 to 720, a multiple of 5. |
| slug | string | no | 3 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. |
| description | string | null | no | Up to 2000 characters. |
| location | string | null | no | Up to 500 characters. |
| timezone | string | no | An IANA time zone. Defaults to the host’s own. |
| availability | object | no | See Availability. Defaults to the host’s working hours, or Monday to Friday 09:00 to 17:00 when they have none. |
| minimum_notice_minutes | number | no | 0 to 43200 (30 days). Defaults to 240. |
| booking_window_days | number | no | 1 to 365. Defaults to 60. |
| active | boolean | no | Defaults to true. |
| hold_times | boolean | no | Defaults to false. Needs windows or slots availability. |
| hosts | array | no | Exactly 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
/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
/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:
| Status | error | When |
|---|---|---|
| 404 | not_found | The page does not exist or books into no calendar you can see. |
| 403 | forbidden | You can see the page but not change it: that takes write access to the calendar it books into. |
| 402 | subscription_required | The host mailbox’s workspace needs an active subscription to take bookings. Checked on create and whenever the host changes. |
| 409 | slug_taken | Another page uses that slug. |
| 422 | invalid_value | A 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. |
| 422 | invalid_uuid | The page uuid in the path is not a valid UUID. |