Apple CloudKit · OpenAPI Overlay 1.0.0

API Evangelist enrichment overlay — Apple CloudKit Web Services Assets Users API

6 actions 6 updates update extends openapi/cloudkit-users-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Apple CloudKit's API. It is a proposal applied on top of the contract, not a document Apple CloudKit publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apis-io-operationx-apis-io-enrichmentexternalDocsx-data-size-limitsx-error-catalogx-idempotencyx-reversibilityx-rate-limits

Targets 6

$.info
$
$.paths['/users/caller'].post
$.paths['/users/discover'].post
$.paths['/users/lookup/email'].post
$.paths['/users/lookup/id'].post

OpenAPI Overlay

Raw ↑ 
# 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 Users API
  version: 1.0.0
x-generated: '2026-09-05'
x-method: generated
x-source: openapi/cloudkit-users-api-openapi.yml + Apple CloudKit Web Services Reference
extends: openapi/cloudkit-users-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['/users/caller'].post
  update:
    x-apis-io-operation:
      operationId: callerUser
      transport: POST JSON
      batch_limit: null
- target: $.paths['/users/discover'].post
  update:
    x-apis-io-operation:
      operationId: discoverUsers
      transport: POST JSON
      batch_limit: null
- target: $.paths['/users/lookup/email'].post
  update:
    x-apis-io-operation:
      operationId: lookupUsersByEmail
      transport: POST JSON
      batch_limit: null
- target: $.paths['/users/lookup/id'].post
  update:
    x-apis-io-operation:
      operationId: lookupUsersById
      transport: POST JSON
      batch_limit: null