User-owned calendars and the events placed on them. Distinct from public profile events; these are the user's personal schedule.
List calendars
Returns the authenticated user's calendars. Calendars are personal; this endpoint is scoped to the caller only.
query Parameters
cursorOpaque cursor returned from a previous list response.
limitMaximum number of items to return per page. Range 1-100, default 20.
List calendars › Responses
Page
has_morenext_cursorRetrieve calendar
Returns a single calendar owned by the authenticated user.
path Parameters
calendar_idPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
Retrieve calendar › Responses
Calendar
idnamedescriptioncoloris_defaultcreated_atupdated_atList calendar events
Returns events on the specified calendar. Includes both user-created calendar events and events synced from active subscriptions.
path Parameters
calendar_idPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
query Parameters
cursorOpaque cursor returned from a previous list response.
limitMaximum number of items to return per page. Range 1-100, default 20.
List calendar events › Responses
Page
has_morenext_cursorCreate calendar event
Creates a personal event on the authenticated user's calendar. Distinct from POST /v1/events, which creates public-facing profile events.
path Parameters
calendar_idPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
Headers
Idempotency-KeyA client-generated identifier (UUIDv4 recommended; 8–255 chars, alphanumeric/underscore/hyphen) for the request. The header is validated and logged, but server-side deduplication is not enforced: resubmitting a create with the same key produces a second resource. Treat creates as non-idempotent and design retries accordingly. Deduplication is planned for a future API version.
Create calendar event › Request Body
titledescriptionlocationstart_time^\d{4}-\d{2}-\d{2}[T…Event start time. Recommended: a naive local time (no offset) interpreted in start_timezone — e.g. "2026-06-06T09:30:00". An offset-bearing RFC 3339 value is also accepted. Must be sent together with start_timezone. Omit for all-day events (use start_date).
end_time^\d{4}-\d{2}-\d{2}[T…Event end time, same formats as start_time. When present, must be sent together with end_timezone. Omit for all-day events (use end_date).
start_timezoneIANA timezone name for start_time. Required. Used for display and recurrence; not used to reinterpret an explicit offset. Must not be null.
end_timezoneIANA timezone name for end_time. Independent of start_timezone. Required when end_time is present. Must not be null.
start_date^\d{4}-\d{2}-\d{2}$All-day start date (YYYY-MM-DD, date only). Required when is_all_day is true; do not send with start_time/end_time.
end_date^\d{4}-\d{2}-\d{2}$All-day end date (YYYY-MM-DD), EXCLUSIVE. Optional; defaults to start_date + 1 day (single day) and must be after start_date (multi-day allowed).
is_all_dayrecurrence_ruleCreate calendar event › Responses
Created
idtitledescriptionlocationstart_timeend_timestart_timezoneend_timezoneis_all_dayrecurrence_rulestatuscreated_atupdated_atDelete calendar event
Deletes a personal calendar event. Subscription-synced events cannot be deleted this way — unsubscribe from the source via deleteSubscription instead.
path Parameters
calendar_idPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
event_idPrefixed unique identifier of the event (e.g., evt_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
Delete calendar event › Responses
Deleted
Update calendar event
Updates a personal calendar event. Only events created via createCalendarEvent are mutable here; subscription-synced events are read-only and changes must be made on the source profile.
path Parameters
calendar_idPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
event_idPrefixed unique identifier of the event (e.g., evt_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
Update calendar event › Request Body
titledescriptionlocationstart_time^\d{4}-\d{2}-\d{2}[T…Event start time (naive local + start_timezone recommended; offset-bearing also accepted). When present, must be sent together with start_timezone.
end_time^\d{4}-\d{2}-\d{2}[T…Event end time, same formats as start_time. When present, must be sent together with end_timezone. Omit for all-day events (use end_date).
start_timezoneIANA timezone name for start_time. Required when start_time is present. Used for display and recurrence; not used to reinterpret an explicit offset. Must not be null.
end_timezoneIANA timezone name for end_time. Independent of start_timezone. Required when end_time is present. Must not be null.
start_date^\d{4}-\d{2}-\d{2}$All-day start date (YYYY-MM-DD, date only). Required when is_all_day is true; do not send with start_time/end_time.
end_date^\d{4}-\d{2}-\d{2}$All-day end date (YYYY-MM-DD), EXCLUSIVE. Optional; defaults to start_date + 1 day (single day) and must be after start_date (multi-day allowed).
is_all_dayrecurrence_ruleUpdate calendar event › Responses
Updated
idtitledescriptionlocationstart_timeend_timestart_timezoneend_timezoneis_all_dayrecurrence_rulestatuscreated_atupdated_at