# Apple CloudKit

> CloudKit is Apple's cloud backend for iOS, iPadOS, macOS, tvOS, watchOS and visionOS apps. CloudKit
> Web Services is its public REST surface, hosted at https://api.apple-cloudkit.com/database/1, which
> lets non-Apple-platform clients read and write a container's public, private or shared database.
> Apple publishes no OpenAPI, no MCP server and no agent card for it; the contract is prose in Apple's
> Documentation Archive, last revised 2016-06-13. This file was generated by API Evangelist from the
> apis.yml record and the artifacts in this repository, not published by Apple.

Generated: 2026-09-05
Method: generated (no /llms.txt is served on developer.apple.com or any CloudKit host — probed 404)
Source: https://github.com/api-evangelist/cloudkit

## How it is shaped

- Base URL: https://api.apple-cloudkit.com/database/1/{container}/{environment}/{database}/{operation}
- container: an iCloud container id, always prefixed "iCloud." (e.g. iCloud.com.example.app)
- environment: development | production — the sandbox is a URL segment, not a separate host or key
- database: public | private | shared
- Every operation is POST with a JSON body; paths name operations, not resources
- Batches carry up to 200 operations; responses carry up to 200 records
- Pagination is a cursor: resultsLimit in, continuationMarker out and back in
- No idempotency key. Writes use optimistic concurrency: send the current recordChangeTag or get CONFLICT (409)
- No reversal operation. A delete through /records/modify cannot be undone through the API

## Authentication

- API token in the query string: ?ckAPIToken=... (identifies the app)
- End-user token: ?ckWebAuthToken=... obtained via the AUTHENTICATION_REQUIRED redirectURL flow; 30 minutes, or 2 weeks with "Keep me signed in"
- Server-to-server: ECDSA prime256v1 signature in X-Apple-CloudKit-Request-SignatureV1 with -KeyID and -ISO8601Date; signed requests expire after 10 minutes
- API-token auth and server-to-server auth must not be combined in one request
- No OAuth, no OIDC, no scopes — authorization comes from the database addressed, container security roles, and record publicPermission

## Docs

- CloudKit Web Services Reference (archived): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/index.html
- Setting up web services (auth, signing): https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/SettingUpWebServices.html
- Error codes: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ErrorCodes.html
- Data size limits: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/PropertyMetrics.html
- Types and dictionaries: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Types.html
- CloudKit JS: https://developer.apple.com/documentation/cloudkitjs
- CloudKit framework: https://developer.apple.com/documentation/cloudkit
- CKTool JS: https://developer.apple.com/documentation/cktooljs
- cktool CLI: https://developer.apple.com/icloud/ck-tool/
- CloudKit Console: https://icloud.developer.apple.com/dashboard/

## Operations

- POST /records/query — query records (queryRecords)
- POST /records/lookup — fetch records by name (lookupRecords)
- POST /records/modify — create, update, delete records (modifyRecords)
- POST /records/changes — fetch record changes (recordChanges)
- POST /records/resolve — resolve share record info (resolveRecords)
- POST /records/accept — accept share records (acceptShare)
- POST /zones/list — list zones (listZones)
- POST /zones/lookup — look up zones (lookupZones)
- POST /zones/modify — create or delete zones (modifyZones)
- POST /zones/changes — fetch zone changes (zoneChanges)
- POST /changes/database — fetch database changes (databaseChanges)
- POST /changes/zone — fetch record zone changes (zoneRecordChanges)
- POST /assets/upload — request asset upload URLs (uploadAssets)
- POST /assets/rereference — re-reference assets (rereferenceAssets)
- POST /subscriptions/list — list subscriptions (listSubscriptions)
- POST /subscriptions/lookup — look up subscriptions (lookupSubscriptions)
- POST /subscriptions/modify — create or delete subscriptions (modifySubscriptions)
- POST /users/caller — fetch caller identity (callerUser)
- POST /users/discover — discover user identities (discoverUsers)
- POST /users/lookup/email — look up users by email (lookupUsersByEmail)
- POST /users/lookup/id — look up users by record name (lookupUsersById)
- POST /tokens/create — create an APNs token (createToken)
- POST /tokens/register — register an APNs token (registerToken)

## Errors

serverErrorCode strings, returned in a JSON body with uuid, reason and sometimes retryAfter/redirectURL:
ACCESS_DENIED (403), ATOMIC_ERROR (400), AUTHENTICATION_FAILED (401), AUTHENTICATION_REQUIRED (421),
BAD_REQUEST (400), CONFLICT (409), EXISTS (409), INTERNAL_ERROR (500), NOT_FOUND (404),
QUOTA_EXCEEDED (413), THROTTLED (429), TRY_AGAIN_LATER (503), VALIDATING_REFERENCE_ERROR (412),
ZONE_NOT_FOUND (404).

## Limits

- 200 operations per request, 200 records per response, 200 tokens per request
- 1 MB maximum record size excluding assets; 50 MB maximum asset file size
- 750 maximum source references to one target where the action is delete-self
- No published requests-per-second rate and no RateLimit-* response headers; THROTTLED (429) carries retryAfter in the body

## What Apple does not publish

- No OpenAPI, Swagger, GraphQL, gRPC or WSDL contract
- No MCP server and no A2A agent card (probed /.well-known/agent-card.json and /.well-known/agent.json on eight hosts — all miss)
- No webhooks: change notification is APNs push via subscriptions, never an HTTP callback
- No deprecation policy, no Sunset headers, no SLA
- No usage pricing or free-tier quota table; access is gated by $99/year Apple Developer Program membership

## Events

- Subscriptions (subscriptions/modify) fire push notifications through APNs
- Web clients register APNs tokens with tokens/create and tokens/register
- There is no webhook endpoint and no AsyncAPI document

## Status

- Developer system status: https://developer.apple.com/system-status/ (names "CloudKit Database" and "CloudKit Console")
- Machine-readable board: https://www.apple.com/support/systemstatus/data/developer/system_status_en_US.js

## Security

- security.txt: https://www.apple.com/.well-known/security.txt
- Apple Security Bounty: https://security.apple.com/bounty/
- ISO/IEC 27001 and ISO/IEC 27018 certified with iCloud in scope: https://support.apple.com/guide/certifications/apple-internet-services-security-apc34d2c0468b/1/web/1.0