Copy page

Getting Started

API change notes

API change notes

Unreleased — agenda

Recurring event creates, updates and reschedules validate the rule against the effective event start before saving. Rules must produce a first occurrence within a bounded work allowance and contain at most 8192 characters; invalid or excessively costly rules return 400 with invalid_recurrence_rule. Rules such as BYDAY=2TU remain supported. This API validation does not replace runtime limits in the agenda or protect direct database writes.

GET /v1/agenda (getAgenda on both MCP routes) reads a combined schedule from Everyday and selected eligible connected calendars. It expands personal recurrence and removes mapped mirror copies. Supply a local date, days (1–31), optional IANA timezone, optional comma-separated calendar_ids, and detail=summary|full. The window must fit within 30 days back and 365 days ahead; these bounds do not guarantee that providers have synced the entire range.

Responses contain at most 500 occurrences, the resolved window, query completeness and metadata for every searched calendar, including empty ones. Check source warnings before asserting availability. full adds descriptions. Only items with editable: true can be changed through the existing calendar-event PATCH route. Connected event IDs use xcev_; they remain stable while the stored row exists, and reimporting can assign a new ID. No endpoint accepts these IDs for writes.

Unreleased — response references

Event and Series responses now include their owning profile_id. RSVPs report their parent event_id, and calendar events report their personal calendar_id. Subscription responses include profile_id and series_id; use subscription_type to identify the source. All values are prefixed public IDs. A profile or series reference can be null when its source is no longer visible, and the unused subscription source is also null.

Unreleased — follow target references

Follow create and list responses now include target_id, the prefixed prf_, ser_, or evt_ identifier of the followed resource. Profile follows consistently use the public following_type: "profile" value. target_id is null only when the original target is no longer visible.

Unreleased — identifier consistency

• Resource IDs now carry an enforced, case-insensitive prefix pattern in REST validation and MCP tool schemas. Calendar-event IDs use cev_; other prefixes remain unchanged.
• RSVP responses no longer expose internal authentication UUIDs, and RSVP creation no longer accepts attendee_user_id. New RSVP rows are owned by the authenticated caller; use attendee contact fields for guest RSVPs.
• RSVP settings no longer return an unusable RSVP-prefixed ID. They remain addressed through their parent event.
• Calendar MCP tools explicitly direct callers to resolve and reuse exact cal_ IDs and to account for paginated event lists.

everyday_id remains a profile handle for links and is restricted to letters, numbers, underscores, dots, and hyphens. It is not a resource ID and must not be passed where a prf_ ID is required.

Unreleased — contract cleanup

This one-time breaking cleanup makes REST and both MCP surfaces follow the reviewed OpenAPI contract, without compatibility shims or a deprecation period.

• Requests reject unknown fields. Ownership, internal IDs, and deletion state cannot be set through generic updates. Use the cancel action for event cancellation.
• Responses omit undocumented fields, including internal Profile ownership and deletion diagnostics. Profile.featured_event_id is removed because the old implementation returned an internal numeric ID rather than the documented public ID.
• The nonexistent subscription fields sync_window_start and sync_window_end are removed.
• Undocumented transparency passthrough is removed. Explicit read/write support is planned for the next release.
• Nested calendar-event and RSVP mutations respect the parent ID in the URL. Malformed cancellation requests fail without cancelling the event.

The API Reference and both MCP tool lists use the same route specification. Future releases remain subject to compatibility review.

Unreleased — calendar workflows

• Discover organizations available for profile creation with GET /v1/organizations. IDs start with org_; the caller's single active owned organization is marked is_default.
• organization_id is optional on profile creation. When omitted, the API uses that default organization. When supplied, it must be an org_ ID returned by organization discovery and the caller must be a member. The create response reports the resolved organization_id.
• Discover connected external calendars with GET /v1/external-calendars. Their IDs start with xcal_; personal cal_ IDs are not subscription destinations.
• Subscription creation uses external_calendar_ids instead of the broken target_calendar_id. Supply a profile or series source. Repeating the request saves/reactivates that source; the external-calendar list replaces its target selection (omitting it selects no external targets). External targets require include_personal_calendar: true, the default.
• consolidate: true explicitly opts into consolidating matching series subscriptions into a profile subscription. It is never implicit. Reactivating with PATCH preserves existing destinations. A cleanup already processing returns 409 subscription_cleanup_in_progress; retry after cleanup finishes.
• Events and calendar events support transparency: "opaque" | "transparent" on reads and writes.
• Series deletion previews include member, exclusive, and shared recurring-event counts.

Both MCP tool lists include organization and external-calendar discovery. These changes are unreleased until review and deployment acceptance complete.