logo
logo

Upload API (V1)

The upload API allows you to upload from other clients than the Sitecore Content Hub™ web UI. For example, it allows you to use Sitecore Connect™ for Creative Cloud™.

The upload API exposes the following endpoints:

  • api/v1.0/upload: requests an upload URL.
  • api/v1.0/upload/assets: uploads (creates) a new asset from an already uploaded file.
  • api/v1.0/upload/assets/{id}: uploads a master file of an existing asset.
  • api/v1.0/upload/assets/{id}/alternative: uploads an alternative file of an existing asset.

A complete upload flow consists of three steps:

  1. Request an upload URL
  2. Upload a file to the received URL
  3. Upload or create a new asset or update an existing one with a master or alternative file

Request an upload URL

To retrieve an upload URL, send a POST request to the endpoint api/v1.0/upload.

The request form body must contain the following fields:

  • fileName - name of the file to upload.
  • fileSize - size of the file to upload.

A successful response returns the upload URL in the location header, and a JSON body containing information structured as follows:

{
   "fileIdentifier": "azr123grz3",
   "storageIdentifier": "weu"
}
  • The fileIdentifier represents the identifier of the file in the system.
  • The storageIdentifier represents the location where the file is stored. It can be null or missing in the JSON.

The upload URL constantly points to an Azure storage blob.

In case of a distributed upload, the API endpoint api/v1.0/upload of the portal application redirects you to the traffic manager and the satellite closest to you creates and returns an upload URL.

Upload a file to the received URL

The received upload URL is a public URL to an Azure storage blob, which means that you can upload files using the Azure blob service REST API.

To perform an upload, send a PUT request to the upload URL with the following required headers:

  • x-ms-blob-type: Azure expects the value to be BlockBlob.
  • x-ms-blob-content-type: the content-type of the file.
  • x-ms-meta-Filename: the name of the file.

Upload a large file to Azure blob storage

If the file is bigger than 200 MB, split it and send each block separately to Azure by extending the upload URL with the query string parameters comp=block&blockid={blockid}:

  • blockid is a valid Base64 string value to identify the block.
  • For a given blob, the length of the specified blockid value must be the same size for each block.

When all the blocks are sent, send another request to the upload URL to notify that the upload is complete, and that all the blocks should be put together:

  • Extend the upload URL with the query string parameter comp=blocklist.
  • The body of the request must be XML formatted and must specifies in which order to load the blocks using their blockid.

The following code snippet shows how to load blocks using blockid:

<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Latest>AAAAAA==</Latest>  
  <Latest>AQAAAA==</Latest>  
  <Latest>AZAAAA==</Latest>  
</BlockList>

This final request requires the following headers:

  • x-ms-blob-content-type: the content-type of the file.
  • x-ms-meta-Filename: the specific name of the file.
Note

For more information, see the Azure put block documentation. Additionally, you can use the JavaScript Azure SDK to perform the previously described actions.

Upload or create a new asset or update existing one with master or alternative file

To create a new asset from an uploaded file, send a POST request to api/v1.0/upload/assets.

To upload a master file of an existing asset, send a POST request to api/v1.0/upload/assets/{id} with the id of the asset.

To upload an alternative file of an existing asset, send a POST request to api/v1.0/upload/assets/{id}/alternative with the id of the asset.

Important

In all cases, the request body must contain the JSON content received previously.

Upload configurations

The uploads are processed by using an upload configuration. Upload configurations may include:

  • maximum allowed file size, which limits the size of files allowed for upload.
  • disallowed extensions, which defines the file extensions not allowed for upload.
  • DefaultUploadConfiguration, which defines the default configuration.
Note

Superusers can override the Repository and Life Cycle of Created Assets upload settings using the ApiUploadConfigurationsetting. To modify this setting, click Manage and, on the Manage page, click Settings. Under ProtalConfiguration, select ApiUploadConfigurationsetting.

Can we improve this article ? Provide feedback