---
title: "Re-reference Existing Assets"
method: POST
path: "/database/{version}/{container}/{environment}/{database}/assets/rereference"
tags: ["Assets"]
---

# Re-reference Existing Assets

`POST /database/{version}/{container}/{environment}/{database}/assets/rereference`

Fetch reusable asset descriptors for assets that already live on other
records, without re-uploading the bytes. Each returned descriptor can be
set on another record's Asset field via `records/modify` to share the
same underlying asset. Assets are deleted only when all references to
them are removed.

Documented in Apple's archived CloudKit Web Services Reference
(`RereferenceAssets`); absent from the current online docs.

## 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
  - `zoneID` ZoneID
    - `zoneName` string
    - `ownerName` string
  - `assets` object[], required — Array of source asset fields to re-reference.
    - `recordName` string, required — Name of the record holding the source asset.
    - `fieldName` string, required — Name of the Asset field on the source record.

## Response `200`

Reusable asset descriptors returned successfully.

- AssetRereferenceResponse — Response body for `assets/rereference`: one reusable asset descriptor per requested asset field, wrapped under `assets`. Verified against the live service: the endpoint validates atomically — a bad entry (e.g. a missing source record) fails the *whole* request with a top-level HTTP 400, so there are no inline per-item failures here (unlike `ModifyResponse`/`LookupResponse`).
  - `assets` AssetValue[]
    - `fileChecksum` string — Checksum of the asset file
    - `size` integer — Size of the asset in bytes
    - `referenceChecksum` string — Checksum of the asset reference
    - `wrappingKey` string — Wrapping key for the asset
    - `receipt` string — Receipt for the asset
    - `downloadURL` string, uri — URL for downloading the asset

## 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-05-31** `44029c7b63a3` — 1 info
  - endpoint added
- **2025-07-05** `a6d50d6e9dde` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/changes/database/:version/:container/:environment/:database/assets/rereference/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)