Files

Initialize a block based file upload job

Changed on Feb 25, 2026

This, along with the set of related APIs enables the upload of large files by splitting the content into multiple blocks, transferred over separate requests. This method is ideal for files larger than 10 MB, offering parallelism, resumability, and efficient error recovery.

NOTE: For files 10 MB or larger, direct upload is not supported. Clients must use this block-based upload workflow. block-based transfer is allowed for any size

Upload Flow Overview

1. Initiate Upload:

Client sends a POST request to initiate the block upload and receives a response with URLs for uploading individual blocks and finalizing the transfer.

2. Upload Blocks:

Client issues PUT requests to the provided Block Transfer URLs, sending file data in chunks. These can be uploaded in parallel.

NOTE: ####Uploading File Blocks After receiving transferLinks, clients can use them to upload individual blocks: PUT <transferURL> <binary data>

Authorization Header: Must NOT be included in the request.

Success Response: 200 OK indicates successful block upload.

Expiration Handling: Each upload session is time-bound. If blocks are not uploaded within the specified expiration window (urlExpirationDate field from the initiation response), the operation may fail.

Always check and respect the urlExpirationDate timestamp in the response from the Block Upload Init endpoint.

3. Finalize Upload:

After all blocks are uploaded, the client calls the Block Finalize URL to trigger the upload to the destination location.

4. Monitor:

Finalize operation's response includes a Monitor URL to check the final status.

Initialize the Block-Based Upload

This endpoint allows clients to initiate the creation of a new file using block-based transfer.

NOTE: The expiration duration of transfer URLs is explicitly provided to the client in the response

post/files/upload/init

Request

Base URL: https://cloudstorage.adobe.io/v1
URL: https://cloudstorage.adobe.io/v1/files/upload/init
Auth: HTTP bearer

Headers

x-request-idstring

Example:1234567890

The X-Request-Id header is used to identify a request.
It can be used to correlate logs and other resources and is intended to be a non-persistent identifier.

Request body

sizeinteger required

The size of the file in bytes.

parentIdstring required

A globally unique identifier for the asset

namestring required

The name of the asset (including the extension, in case of a file)

The name must not be a

reserved Windows name
- CON
- PRN
- AUX
- NUL
- COM1 through COM9
- LPT1 through LPT9
contain any of the following characters:
- \
- /
- :
- *
- ?
- "
- |
- >
- <

mediaTypestring required

The MIME type of the file

blockSizeinteger

The size of each block in bytes. The block size returned may differ from the size requested.

Example request

{
  "size": 1048576,
  "parentId": "urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174",
  "mediaType": "image/jpeg",
  "blockSize": 1048576,
  "options": {
    "autorename": true
  }
}

Response

Success - Upload Id along with urls for upload

uploadIdstring

The upload id

blockSizeinteger

The size of each block in bytes

urlExpirationDatestring date-time

Example response

{
  "uploadId": "123e4567-e89b-12d3-a456-426614174000",
  "blockSize": 1048576,
  "urlExpirationDate": "2021-01-01T00:00:00Z",
  "transferLinks": [
    {
      "partNumber": 1
    }
  ]
}

Changes

Feb 25, 2026240b6278279c Revision changes
- breaking
  added the pattern ^(?!^([Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])$)[^\\\/:*?"|><]+$ to the request property
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- warning
  added the new conflict enum value to the response property for the response status
- info
  the request property's minLength was decreased from 1 to 0
Dec 18, 202501600f5358e9 Revision changes
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new operation_timeout enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new payload_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- warning
  added the new resource_too_large enum value to the response property for the response status
- info
  added the new optional request property

Operation history (4 revisions)