---
title: "Modify Zones"
method: POST
path: "/database/{version}/{container}/{environment}/{database}/zones/modify"
tags: ["Zones"]
---

# Modify Zones

`POST /database/{version}/{container}/{environment}/{database}/zones/modify`

Create or delete zones (only supported in private database)

## Path parameters

- `version` string, required — Protocol version
- `container` string, required — Container ID (begins with "iCloud.")
- `environment` 'development' | 'production', required — Container environment
- `database` 'public' | 'private' | 'shared', required — Database scope

## Request body

- object
  - `operations` ZoneOperation[]
    - `operationType` 'create' | 'delete'
    - `zone` object
      - `zoneID` ZoneID
        - `zoneName` string
        - `ownerName` string

## Response `200`

Zones modified successfully

- ZonesModifyResponse — Response body of `zones/modify`. Each entry in `zones` is either a Zone dictionary (success) or a Zone Fetch Error dictionary (failure), per Apple's archived reference. `zones/modify` is a batch endpoint whose realistic failure mode is partial — creating a zone that already exists alongside zones that create cleanly — so a failed entry must not discard the entries that succeeded (see issue #431).
  - `zones` union[]
    - union
      - ZoneFetchFailure — Per-zone error returned inline in the `zones` array of a 200 zone response (`changes/database`, `changes/zone`, `zones/modify`). Mirrors `RecordOperationFailure` for records, but keyed by `zoneID`.
        - `zoneID` ZoneID
          - `zoneName` string
          - `ownerName` string
        - `serverErrorCode` 'ACCESS_DENIED' | 'ATOMIC_ERROR' | 'AUTHENTICATION_FAILED' | 'AUTHENTICATION_REQUIRED' | 'BAD_REQUEST' | 'CONFLICT' | 'EXISTS' | 'INTERNAL_ERROR' | 'NOT_FOUND' | 'QUOTA_EXCEEDED' | 'THROTTLED' | 'TRY_AGAIN_LATER' | 'VALIDATING_REFERENCE_ERROR' | 'ZONE_NOT_FOUND', required — The CloudKit server error code returned in a per-item failure entry (record or subscription) inline in a 200 modify/lookup response. Shared by `RecordOperationFailure` and `SubscriptionOperationFailure` via `OperationFailureCommon`. Distinct from `ErrorResponse`'s `serverErrorCode`, which carries a broader set of codes for top-level 4xx/5xx HTTP failures.
        - `reason` string — A string indicating the reason for the error.
        - `retryAfter` integer — Suggested seconds to wait before retrying. Absent if not retryable.
        - `uuid` string — A unique identifier for this error.
        - `redirectURL` string — Redirect URL for sign-in; present when serverErrorCode is AUTHENTICATION_REQUIRED.
      - Zone — A record zone as returned by the zone endpoints (`zones/list`, `zones/lookup`, `zones/modify`, `zones/changes`). Matches the "Zone Dictionary" in Apple's archived CloudKit Web Services Reference, which documents exactly three keys: `zoneID`, `syncToken`, and `atomic`. `isEager` is deliberately absent — it appears in no primary Apple source (see issue #386).
        - `zoneID` ZoneID
          - `zoneName` string
          - `ownerName` string
        - `syncToken` string — The current point in the zone's change history.
        - `atomic` boolean — A Boolean value indicating whether this zone supports atomic operations.

## Other responses

- `400` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `401` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)

## Changes

- **2026-08-29** `db45a101c485` — 2 breaking, 3 warning
  - added `#/components/schemas/ZoneFetchFailure, #/components/schemas/Zone` to the `zones/items/` response property `oneOf` list for the response status `200`
  - the `zones/items/` response's property type/format changed from `object`/`` to ``/`` for status `200`
  - removed the optional property `zones/items/atomic` from the response with the `200` status
  - removed the optional property `zones/items/syncToken` from the response with the `200` status
  - …1 more
- **2026-08-27** `3ea965df5f01` — 2 info
  - added the optional property `zones/items/atomic` to the response with the `200` status
  - added the optional property `zones/items/syncToken` to the response with the `200` status
- **2025-07-06** `a17a324ec78e` — 28 warning, 1 info
  - added the new `ACCESS_DENIED` enum value to the `serverErrorCode` response property for the response status `400`
  - added the new `ACCESS_DENIED` enum value to the `serverErrorCode` response property for the response status `401`
  - added the new `ATOMIC_ERROR` enum value to the `serverErrorCode` response property for the response status `400`
  - added the new `ATOMIC_ERROR` enum value to the `serverErrorCode` response property for the response status `401`
  - …25 more
- …earlier changes not shown

[Full history](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/changes/database/:version/:container/:environment/:database/zones/modify/post.md)

---

[API](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api.md) · [All operations](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brightdigit/apple-cloudkit-web-services-api/revisions/db45a101c485/schema)