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_id^cal_[0-9a-fA-F]{32}… · requiredPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
Retrieve calendar › Responses
Calendar
id^cal_[0-9a-fA-F]{32}…namedescriptioncoloris_defaultcreated_atupdated_atList calendar events
Stored events on one Everyday calendar, ordered by creation time. Includes personal events and materialized profile subscription events; recurring personal series remain stored rows with a rule. Connected provider events are excluded. Use GET /v1/agenda for a time-window schedule.
path Parameters
calendar_id^cal_[0-9a-fA-F]{32}… · requiredPrefixed 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_id^cal_[0-9a-fA-F]{32}… · requiredPrefixed 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_ruleSingle RRULE text (optional RRULE: prefix), or null to clear recurrence. Must produce a first occurrence within a bounded work allowance using the effective event start. Invalid or excessively costly rules return 400 invalid_recurrence_rule. Advanced rules such as BYDAY=2TU are supported.
transparencyRFC 5545 busy/free behavior: opaque blocks time; transparent does not.
Create calendar event › Responses
Created
id^cev_[0-9a-fA-F]{32}…calendar_id^cal_[0-9a-fA-F]{32}…Personal calendar containing this event.
titledescriptionlocationstart_timeend_timestart_timezoneend_timezoneis_all_dayrecurrence_rulestatuscreated_atupdated_attransparencyRFC 5545 busy/free behavior: opaque blocks time; transparent does not.
Delete 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_id^cal_[0-9a-fA-F]{32}… · requiredPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
event_id^cev_[0-9a-fA-F]{32}… · requiredPrefixed unique identifier of the calendar event (e.g., cev_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_id^cal_[0-9a-fA-F]{32}… · requiredPrefixed unique identifier of the calendar (e.g., cal_8f3ab21e49c44c8baf7b5e4a1b2c3d4e).
event_id^cev_[0-9a-fA-F]{32}… · requiredPrefixed unique identifier of the calendar event (e.g., cev_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_ruleSingle RRULE text (optional RRULE: prefix), or null to clear recurrence. Must produce a first occurrence within a bounded work allowance using the effective event start. Invalid or excessively costly rules return 400 invalid_recurrence_rule. Advanced rules such as BYDAY=2TU are supported.
transparencyRFC 5545 busy/free behavior: opaque blocks time; transparent does not.
Update calendar event › Responses
Updated
id^cev_[0-9a-fA-F]{32}…calendar_id^cal_[0-9a-fA-F]{32}…Personal calendar containing this event.
titledescriptionlocationstart_timeend_timestart_timezoneend_timezoneis_all_dayrecurrence_rulestatuscreated_atupdated_attransparencyRFC 5545 busy/free behavior: opaque blocks time; transparent does not.
List connected external calendars
Lists connected calendars visible to the caller. Use xcal_ IDs as external subscription targets; cal_ identifies an Everyday personal calendar.
query Parameters
cursorOpaque cursor returned from a previous list response.
limitMaximum number of items to return per page. Range 1-100, default 20.
List connected external calendars › Responses
Page
has_morenext_cursorRead your agenda
Read-only combined schedule over 1–31 local days. The entire window must fall within 30 days back and 365 days ahead, measured in the resolved timezone. These are query bounds, not a promise of source coverage. At most 500 sorted occurrences; complete=false reports query or expansion truncation. Sources include empty calendars; warnings indicate unknown, failed, disabled, old, or unverified sync state. Connected calendars reflect available synced data, not a live provider request. No-end events are points; all-day end dates are exclusive. RSVPs not saved to a calendar are excluded.
query Parameters
dateFirst local calendar day, YYYY-MM-DD. Defaults to today in the resolved timezone.
daysWindow length in local days. For this week, choose the week start as date; seven days from today is a rolling week.
timezoneIANA timezone. Defaults to the saved user timezone, then UTC.
calendar_idsOptional comma-separated list of 1–100 exact cal_ or xcal_ IDs. Defaults to all Everyday calendars and selected eligible connected calendars.
detailSummary includes titles, times, location and source. Full also includes description.
Read your agenda › Responses
Combined agenda of matching stored occurrences
completeWhether the query and expansion returned all matching stored data. Does not guarantee provider coverage or freshness.
incomplete_reason