# Generated by the API Evangelist enrichment pipeline. Does not mutate the OpenAPI it extends.
overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay — Apple CloudKit Web Services Assets Changes API
  version: 1.0.0
x-generated: '2026-09-05'
x-method: generated
x-source: openapi/cloudkit-changes-api-openapi.yml + Apple CloudKit Web Services Reference
extends: openapi/cloudkit-changes-api-openapi.yml
actions:
- target: $.info
  update:
    x-apis-io-enrichment:
      provider: Apple
      note: Apple publishes no machine-readable contract for CloudKit Web Services. This description is
        API Evangelist's best-effort reading of Apple's archived CloudKit Web Services Reference; the
        overlay records the runtime semantics Apple documents in prose so they travel with the spec.
      contract_published_by_provider: false
      documentation: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/index.html
- target: $
  update:
    externalDocs:
      description: CloudKit Web Services Reference (Apple Documentation Archive)
      url: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/index.html
    x-data-size-limits:
      max_operations_per_request: 200
      max_records_per_response: 200
      max_tokens_per_request: 200
      max_record_size_mb: 1
      max_asset_file_size_mb: 50
      max_delete_self_references: 750
    x-error-catalog:
      format: custom-json
      envelope:
      - uuid
      - serverErrorCode
      - reason
      - retryAfter
      - redirectURL
      artifact: errors/cloudkit-problem-types.yml
      source: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ErrorCodes.html
    x-idempotency:
      supported: false
      coverage: none
      concurrency: recordChangeTag optimistic concurrency; stale tag returns CONFLICT (409)
      artifact: conventions/cloudkit-conventions.yml
    x-reversibility:
      status: none
      note: No reversal, undo or restore operation is published for any write.
      artifact: conventions/cloudkit-conventions.yml
    x-rate-limits:
      headers: null
      exhaustion_status: 429
      error_code: THROTTLED
      retry_signal: retryAfter (seconds, JSON body)
      artifact: rate-limits/cloudkit-rate-limits.yml
    x-environments:
    - development
    - production
    x-authentication:
      artifact: authentication/cloudkit-authentication.yml
      schemes:
      - cloudKitApiToken (query ckAPIToken)
      - ckWebAuthToken (query, end-user)
      - serverToServer (ECDSA, X-Apple-CloudKit-Request-SignatureV1)
      mutually_exclusive:
      - cloudKitApiToken
      - serverToServer
- target: $.paths['/changes/database'].post
  update:
    x-apis-io-operation:
      operationId: databaseChanges
      transport: POST JSON
      batch_limit: null
- target: $.paths['/changes/zone'].post
  update:
    x-apis-io-operation:
      operationId: zoneRecordChanges
      transport: POST JSON
      batch_limit: null