# Apple Calendar API: read and create events

Source: https://developer.nylas.com/docs/cookbook/calendar/apple-calendar-api/

If you searched for an "Apple Calendar API," you probably expected a developer portal, an SDK, and REST endpoints. Apple offers none of those. iCloud Calendar runs only on CalDAV, an XML-based protocol from the early 2000s that has no JSON, no OAuth, and no developer console. This page explains what Apple actually provides, then points you to the task recipes for reading and creating events through the Nylas Calendar API.

## Does Apple have a public calendar API?

No. Apple provides no public REST calendar API, no SDK, and no developer portal for iCloud Calendar. The only programmatic access is CalDAV, a 20-year-old XML protocol over WebDAV, secured with manually generated app-specific passwords. Nylas wraps CalDAV behind a JSON Events API that normalizes iCloud, Google, and Microsoft as 3 providers under one set of endpoints, so you can skip the protocol entirely.

## What does Apple actually offer for calendar access?

Apple ships CalDAV as the single supported integration path for iCloud Calendar. CalDAV uses WebDAV extensions with XML request and response bodies, persistent connections per user, and iCalendar (RFC 5545) payloads for every event. There is no developer dashboard, no API key, and no way to generate credentials programmatically. Each user must create an app-specific password of 16 characters by hand in their Apple ID settings, and CalDAV covers exactly 1 provider, so it pulls in no other calendar source. CalDAV also lacks native push, so detecting changes means polling on an interval you maintain yourself. For a single-provider hobby project this is workable, but for production apps the engineering cost adds up fast across reconnection logic, XML parsing, and sync-state management.

## CalDAV vs the Nylas unified API

The table below compares building directly on Apple's CalDAV against using the Nylas Calendar API, which normalizes iCloud alongside Google and Microsoft through one set of endpoints. Across all 3 providers you call the same `GET` and `POST` routes, which removes most of the per-provider branching you would otherwise write.

| Capability             | Apple CalDAV (direct)              | Nylas unified API                          |
| ---------------------- | ---------------------------------- | ------------------------------------------ |
| Data format            | XML over WebDAV                    | JSON over REST                             |
| Authentication         | App-specific password, manual      | Hosted OAuth or BYO, Nylas-managed         |
| Event creation         | Hand-built ICS in a PUT request    | Single `POST` with a JSON body             |
| Change notifications   | None, you poll                     | Webhooks across every provider             |
| Multi-provider support | iCloud only                        | iCloud, Google, and Microsoft, one API     |
| Connection handling    | You maintain sessions per user     | Pooled and reconnected for you             |

If you only need iCloud and are comfortable parsing XML, CalDAV works. For most teams, the unified API removes weeks of protocol work.

## How do app-specific passwords work for iCloud?

iCloud blocks third-party access with a normal Apple ID password. Each user must instead generate a 16-character app-specific password in their Apple ID account, then supply that value when they connect through Nylas. Because this step cannot be automated, onboarding 200 users means 200 manual password steps, since Apple exposes no endpoint for minting these credentials. Plan your onboarding around it: show clear instructions, and expect that a user who pastes their regular password will fail authentication every time. Passwords can also be revoked at any moment, which silently invalidates the grant. There is no proactive signal before the next sync fails, so listen for the `grant.expired` event through [webhooks](/docs/v3/notifications/) and prompt the user to reconnect. See Apple's [app-specific password instructions](https://support.apple.com/en-us/102654) for the exact steps users follow.

## How do I read and create iCloud events?

Once a grant exists, you read events with `GET /v3/grants/{grant_id}/events?calendar_id=...` and create them with `POST` to the same path. Both calls take a real `calendar_id`, because iCloud rejects the `calendar_id=primary` shortcut that works on Google and Microsoft, so fetch the ID first with List Calendars. Each list request defaults to 50 events per page and returns up to 200 with `limit`, sorted by start time. The two task recipes below cover the full request and response bodies, SDK samples in five languages, filtering rules, and the iCloud-specific behaviors you should plan around. This page intentionally summarizes rather than repeats those code blocks.

- [List iCloud calendar events](/docs/cookbook/calendar/events/list-events-icloud/) covers reading events, the one-year time range cap, and limited CalDAV filter support.
- [Create iCloud calendar events](/docs/cookbook/calendar/events/create-events-icloud/) covers writing events, participant invitations sent as ICS attachments, and the simpler event model.

## What should I know before choosing CalDAV or Nylas?

Decide based on scope. If iCloud is your only target and you accept ongoing maintenance, direct CalDAV avoids a dependency. If you support more than one provider, or want to ship in days rather than weeks, the unified API is the faster path. Either way, remember three constraints that apply to every iCloud integration: app-specific passwords are mandatory and manual, there is no `primary` calendar alias, and the read range between `start` and `end` cannot exceed 1 year per request. Email and calendar both connect through the same iCloud connector, and message data is cached for 90 days. The [iCloud provider guide](/docs/provider-guides/icloud/) walks through connector setup, both authentication flows, and the rate limits Apple enforces.

## What's next

- [List iCloud calendar events](/docs/cookbook/calendar/events/list-events-icloud/) for the read path with full code samples
- [Create iCloud calendar events](/docs/cookbook/calendar/events/create-events-icloud/) for the write path with full code samples
- [iCloud provider guide](/docs/provider-guides/icloud/) for connector setup and authentication
- [Events API reference](/docs/reference/api/events/) for every endpoint and parameter
- [App passwords guide](/docs/provider-guides/app-passwords/) for generating app-specific passwords
- [Webhooks](/docs/v3/notifications/) for change notifications instead of polling