iCloud Web API Notes

Authentication

iCloud web APIs use cookie-based authentication. The browser session at icloud.com carries the necessary cookies (X-APPLE-WEBAUTH-VALIDATE, X-APPLE-WEB-ID, etc.). All requests must include credentials: "include".

Session Discovery

POST https://setup.icloud.com/setup/ws/1/validate
  ?clientBuildNumber=2618Build21
  &clientMasteringNumber=2618Build21
  &clientId=<any-uuid>

Returns:

• dsInfo.dsid — the user's Directory Services ID (e.g., 17099314)
• webservices.calendar.url — e.g., https://p27-calendarws.icloud.com:443
• webservices.ckdatabasews.url — e.g., https://p27-ckdatabasews.icloud.com:443
• webservices.notes.url — e.g., https://p49-notesws.icloud.com:443

The pXX prefix varies per user (server partition).

Calendar API

Get Events

GET https://p27-calendarws.icloud.com/ca/events
  ?startDate=2026-05-27
  &endDate=2026-06-03
  &lang=en-us
  &usertz=Europe%2FBerlin
  &clientBuildNumber=2618Build21
  &clientMasteringNumber=2618Build21
  &clientId=<uuid>
  &dsid=<dsid>

Response: { Event: [...], Recurrence: [...] }

Event Structure

{
  "title": "Meeting",
  "guid": "UUID",
  "pGuid": "calendar-collection-guid",
  "allDay": false,
  "duration": 60,
  "tz": "Europe/Berlin",
  "localStartDate": [20260530, 2026, 5, 30, 20, 0, 1200],
  "localEndDate": [20260530, 2026, 5, 30, 21, 0, 180],
  "startDate": [20260530, 2026, 5, 30, 20, 0, 1200],
  "endDate": [20260530, 2026, 5, 30, 21, 0, 180],
  "location": "Room 42",
  "description": "HTML or plain text",
  "recurrenceMaster": false,
  "recurrence": "GUID*MME-RID"
}

Date array format: [YYYYMMDD, year, month, day, hour, minute, minuteOfDay]

• Index 6 is minute-of-day (0-1440)

Other Calendar Endpoints

• GET /ca/alarmtriggers — upcoming alarms
• GET /ca/state — calendar sync state
• GET /ca/startup — full startup payload (may return 400 without proper headers)

Notes API (CloudKit)

Notes uses CloudKit Database Service (ckdatabasews).

Zone Discovery

POST https://p27-ckdatabasews.icloud.com/database/1/com.apple.notes/production/private/zones/list
  ?clientBuildNumber=2618Build21&clientId=<uuid>&dsid=<dsid>
Body: {}

Returns zones including Notes zone with ownerRecordName.

Fetch Notes (Changes API)

The query endpoint doesn't work for Notes (type not marked indexable). Use changes/zone instead:

POST https://p27-ckdatabasews.icloud.com/database/1/com.apple.notes/production/private/changes/zone
  ?clientBuildNumber=2618Build21&clientId=<uuid>&dsid=<dsid>
Body: {
  "zones": [{
    "zoneID": { "zoneName": "Notes", "ownerRecordName": "<owner>" }
  }]
}

Response includes syncToken and moreComing for pagination. Pass syncToken in subsequent requests to get next page.

Record Types in Notes Zone

• Note — the note record
• Folder_UserSpecific — folder metadata
• Note_UserSpecific — per-user note state
• Attachment — file attachments
• InlineAttachment — inline images/files
• Media — media records

Note Record Fields

Decoding Note Content

1. Title/Snippet: Simple base64 → UTF-8 decode

   const binary = atob(b64Value);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
   const text = new TextDecoder("utf-8").decode(bytes);

2. Full Content (TextDataEncrypted):

   • Base64 decode → gzip decompress → protobuf binary
   • Text can be extracted by stripping non-printable characters
   • The protobuf format is Apple's proprietary TTML-like note format
   • Readable text is interspersed with control bytes

   // Decompress using DecompressionStream API
   const ds = new DecompressionStream("gzip");
   // ... write bytes, read chunks ...
   const text = new TextDecoder("utf-8", { fatal: false }).decode(result);
   const readable = text.replace(/[^\x20-\x7E\u00A0-\uFFFF\n\r\t]/g, "").trim();

Request Headers

All requests use:

• Content-Type: text/plain (avoids CORS preflight)
• Origin: https://www.icloud.com
• credentials: "include" (sends cookies)

Using application/json as Content-Type triggers CORS preflight which may fail.

Client Parameters

All endpoints require:

• clientBuildNumber=2618Build21 (may change with iCloud updates)
• clientMasteringNumber=2618Build21
• clientId=<any-string> (can be any identifier)
• dsid=<user-dsid> (from validate response)