---
title: "Request Asset Upload URLs"
method: POST
path: "/database/{version}/{container}/{environment}/{database}/assets/upload"
tags: ["Assets"]
---

# Request Asset Upload URLs

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

Request upload URLs for asset fields. This is the first step in a two-step process:
1. Request upload URLs by specifying the record type and field name
2. Upload the actual binary data to the returned URL (separate HTTP request)

Upload URLs are valid for 15 minutes. Maximum file size is 15 MB.

## 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
  - `tokens` object[], required — Array of asset fields to request upload URLs for
    - `recordName` string — Unique name to identify the record. Defaults to random UUID if not specified.
    - `recordType` string, required — Name of the record type
    - `fieldName` string, required — Name of the Asset or Asset list field

## Response `200`

Upload URLs returned successfully

- AssetUploadResponse
  - `tokens` object[]
    - `url` string
    - `recordName` string
    - `fieldName` string

## 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-02-05** `d33cda723a4a` — 1 breaking, 1 info
  - removed the media type `multipart/form-data` from the request body
  - added the media type `application/json` to the request body
- **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
- **2025-07-05** `a6d50d6e9dde` — 1 breaking, 30 info
  - removed the media type `application/json` from the request body
  - api operation id `uploadAssets` removed and replaced with ``
  - added the media type `multipart/form-data` to the request body
  - removed the `ACCESS_DENIED` enum value from the `serverErrorCode` response property for the response status `400`
  - …27 more

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