Calendar API

Returns every calendar you can see in the token’s workspace, one entry per mailbox it is linked to, ordered by position and then name. Not paginated. Scope calendar.read.

curl https://api.cirrux.co/public_api/v1/calendars \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "list",
  "url": "/v1/calendars",
  "has_more": false,
  "data": [
    { "object": "calendar", "name": "Work", "calendar_uuid": "9a8b7c6d-…", … }
  ]
}

Returns everything on a calendar between time_min and time_max, with recurring series expanded into their occurrences, ordered by start time. All-day and timed events are ordered together. A calendar you cannot see is 404 not_found. Scope calendar.read.

An event is in the window when it overlaps it, not only when it starts in it: it is included when it starts before time_max and ends after time_min. For a window from 09:00 to 17:00:

• an event from 08:00 to 10:00 is included, because it is still running at 09:00;
• an event from 16:00 to 18:00 is included, because it has started before 17:00;
• an event from 08:00 to 09:00 is not, because it ends exactly as the window opens;
• an event starting at 17:00 is not, because the window has closed.

The same holds for each occurrence of a series and for all-day events, so a three-day conference that began yesterday shows up in today’s window. If you only want events that start inside the window, filter on start yourself. The window the server used comes back in the response as time_min, time_max (in UTC) and timezone.

While has_more is true, ask for the next page with cursor set to next_cursor, and the same time_min, time_max and timezone as the first request. An unreadable cursor starts again from the first page.

curl -G https://api.cirrux.co/public_api/v1/calendars/9a8b7c6d-…/events \
  -d time_min=2026-09-07 \
  -d time_max=2026-09-14 \
  -d timezone=Europe/Amsterdam \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "list",
  "url": "/v1/calendars/9a8b7c6d-2222-4e5f-9a1b-000000000002/events",
  "time_min": "2026-09-06T22:00:00Z",
  "time_max": "2026-09-13T22:00:00Z",
  "timezone": "Europe/Amsterdam",
  "has_more": false,
  "data": [
    { "id": "3b0c9e2a-…_20260909T070000Z", "title": "Standup", … },
    { "id": "5d4e3f2a-…", "title": "Offsite", "all_day": true, … }
  ]
}

Creates an event, or a recurring series when you send recurrence. You are the organizer, through the mailbox the calendar belongs to; the organizer cannot be set. Guests in attendees are emailed an invitation. Returns 201 with the event object. For a series that is the series itself: its id is the series uuid, and start and end are those of its first occurrence. Unknown fields are refused with 422 invalid_value rather than ignored, so a typo such as summary for title cannot silently lose data. Scope calendar.write.

curl https://api.cirrux.co/public_api/v1/calendars/9a8b7c6d-…/events \
  -H "Authorization: Bearer $CIRRUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Standup",
    "location": "Room 2",
    "start": {
      "date_time": "2026-09-02T09:00",
      "time_zone": "Europe/Amsterdam"
    },
    "end": {
      "date_time": "2026-09-02T09:15",
      "time_zone": "Europe/Amsterdam"
    },
    "recurrence": "FREQ=WEEKLY;BYDAY=WE",
    "attendees": [{ "email": "sam@example.com", "name": "Sam" }]
  }'

Takes the same fields as creating an event, none of them required: only the fields in the body change, and anything you leave out stays as it is. start and end still go together. Sending attendees replaces the guest list, so include the guests you want to keep. The id decides what you change: an event’s uuid changes the event, which for a recurring event is the whole series, and an occurrence id changes only that occurrence (see Recurring events). Guests are emailed the update. Returns 200 with the event object. Scope calendar.write.

curl https://api.cirrux.co/public_api/v1/calendars/9a8b7c6d-…/events/3b0c9e2a-… \
  -H "Authorization: Bearer $CIRRUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Daily standup" }'

Responding to an invitation. When you are a guest rather than the organizer, the only thing you can change is your own response. Update the event by its uuid with attendees holding an entry for your own address and the new status; the rest of the body is ignored, and the organizer is emailed your reply. On a series, that answers for every occurrence. Responding to a single occurrence is not supported yet: an occurrence id on an event you do not organize is 403 not_organizer.

{ "attendees": [{ "email": "jane@example.com", "status": "accepted" }] }

An event’s uuid deletes the event, which for a recurring event is the whole series, including occurrences that were edited on their own and every part of a series that was split. An occurrence id cancels only that occurrence and leaves the rest of the series alone. Guests are emailed a cancellation either way. Only the organizer can delete. Returns 204 with no body. Scope calendar.write.

curl -X DELETE "https://api.cirrux.co/public_api/v1/calendars/9a8b7c6d-…/events/3b0c9e2a-…_20260909T070000Z" \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

A recurring event is stored once, as a series with an RRULE. The list endpoint expands it, so every repetition in the window is its own item, with an id of the form <series_uuid>_<recurrence_id>: for example 3b0c9e2a-…_20260909T070000Z for the 9 September standup. The recurrence_id names the slot the rule produced, and stays the same when that occurrence is moved to another time, so the id keeps working.

Which id you send to update or delete decides what changes:

• <series_uuid> is the whole series. Update changes every occurrence; delete removes the series, with every occurrence that was edited on its own.
• <series_uuid>_<recurrence_id> is one occurrence. Update changes just that occurrence: the first time, it is split out of the series, comes back with is_exception: true, and keeps its own start and end unless you send new ones. Delete cancels just that occurrence.

An occurrence that was edited on its own has an event_uuid of its own. Always address it by its occurrence id, never by that event_uuid, which is refused with 422 use_occurrence_id. An occurrence id the series never produces, or that was already cancelled, is 404 not_found. Changing one occurrence or the shape of a series is up to the organizer: a guest gets 403 not_organizer.

On top of the shared errors, calendar endpoints can return: