Introduction to AEM as a Cloud Service Asset Upload HTTP API

June 6, 2021

In AEM as a Cloud Service, image processing has been moved to the Asset Compute Microservice. Binary files are uploaded directly to blob storage instead of streaming through the AEM JVM.  In this post, I explain how to get started with the asset upload HTTP API. I review and demonstrate the below-illustrated steps ( 1, 2, and 3) using Postman as a client application.

Note: The Asset Upload HTTP API only works on Cloud Service, not for local SDK


Note: Adobe  provides the AEM Upload tool to make uploading easier, and can be used as a command line executable or required as a Node.js module.

Asset Upload HTTP API
credit Adobe for original image source



Asset Upload

Note: Before you begin, create a user in AEM with sufficient permission to upload assets and create a folder within the asset dam to upload to. For the sake of demo and simplicity, I am using the basic authentication but Service Token base authentication is the preferred method

1. Make a request for upload to AEM

The first step in the sequence is to make a request to AEM, relaying the intent to upload files. This requires authenticating with AEM and providing details about the assets you intend to upload (e.g. file name, file size).

The URI format for this POST call is: https://<aem-url>/content/dam/<asset-folder>.initiateUpload.json

  • Add Basic Auth Credentials

    Postman Basic Auth

  • Add Body

    Postman Body

  • Submit and review response body

    Postman response

Note: Response object properties will be used in the next steps:

folderPath, minPartSize,maxPartSize,files,uploadURIs,mimeType,uploadToken,completeURI


  • Review response cookies

    Note: All corresponding calls to AEM should have the affinity cookie set on the request. The purpose of the affinity cookie is to tell AEM to use the same node in the cluster to handle the requests.


2. Upload binary to the blob store

The response from the first call will contain a list of pre-signed upload URLs, which will be used to upload directly to the blob store. 

Make a PUT request to the pre-signed upload URI that was included in the previous response.

  • Remove Authentication

    Postman remove authentication

  • Add Body, Submit and confirm the request was successful

    Postman binary body

3. Make a request to complete in AEM

After the binaries have been successfully uploaded to the blob store, it is necessary to make a final request to complete the upload with AEM. Assets will not appear within AEM until this final API call is completed.

This call will require a few details from the initial request-response: upload token, complete URI, fileName

Make a POST call to the complete URI returned from the initial request.

  • Add Basic Auth Credentials

    Postman authentication tab

  • Add affinity Cookie

    Note: The corresponding calls to AEM should have the affinity cookie set on the request. If Token-Based Authentication was used, then the x-aem-affinity-type: api header would be passed with the request instead of the Affinity cookie.

  • Add Body, Submit and confirm the request was successful

    Postman Body

View Uploaded Asset in AEM

When the final step of the request sequence is complete, AEM will run the Asset Cloud Post-Processing Workflow. You can navigate to your asset folder and confirm your upload was a success.

Asset Upload HTTP API Success


Part Splitting Use-Cases

In this introduction, I upload a standard web image file (245k). When uploading either a single large file or multiple files, it will be necessary to split the binary uploads into multiple requests. Each part should respect the minPartSize and maxPartSize values returned from the initial upload request.




*A big thank you to Kiran Murugulla and Kaushal Mall for their contributions and feedback in putting this together!