logo

Upload API (V2)

Using the Upload API, you can upload content from other clients rather than from the Sitecore Content Hub™ web UI.

The upload API exposes the following endpoints:

  • api/v2.0/upload: requests an upload URL.
  • api/v2.0/upload/finalize: finalizes the upload.
Note

To upload files larger than 1000000 bytes (approximately 1 MB), see Upload large files.

A complete upload flow consists of three steps:

  1. Request an upload
  2. Perform the upload
  3. Finalize the upload

Request an upload

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

The request body should have the following structure:

{
   "file_name":"<filename>",
   "file_size":"<filesize>",
   "upload_configuration":{
      "name":"<upload configuration name>",
      "parameters":{
         ...
      }
   },
   "action":{
      "name":"<action name>",
      "parameters":{
         ...
      }
   }
}
  • fileName: name of the file to upload
  • fileSize: size of the file to upload
  • upload_configuration: upload configuration
  • action: actions to perform on the file

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

{
  "upload_identifier": "<uploadID>",
  "fileIdentifier": "<fileID>"
}
  • upload_identifier: identifier of the upload job.
  • fileIdentifier: identifier of the file in the system.
Note

The returned upload URL is similar to the following example: /api/v2.0/upload/process?key=local-64215f47c&name=Upload_c3de2f26-8b22.jpg&expires=2020-11-20T17:00:53.1850293+00:00&signature=bQybo8zZb-Q. This generated upload URL is only available for 5 minutes. This is a hard-coded limitation and means that uploads must be finalized within this 5-minute timeframe.

Upload configurations

An upload configuration describes a context defined by an administrator or a superuser for which a type of upload is allowed. The upload configuration tells the system which file extensions are allowed, the maximum file size, in which repository and status the asset should be created, and so on.

The required parameters depend on the upload configuration itself. For example, if you want to upload a logo, you need to include a parameter named theme to indicate which theme the upload logo should be linked to.

Existing configurations:

  • AssetUploadConfiguration
  • ImportPackageConfiguration
  • ImportLocalizationsConfiguration
  • ImportDataConfiguration

Supported actions

The supported actions to perform on a file are:

ActionDescription
NewAssetCreates a new asset and sets the uploaded file as the main file for the newly created asset.
NewMainFileChanges the main file with the uploaded file for an existing asset; requires the AssetId action parameter to specify which asset must be updated.
NewAlternativeFileChanges the alternative file with the uploaded file for an existing asset; requires the AssetId action parameter to specify which asset must be updated.
ImportConsiders the uploaded file as an import and executes an import job for it.

As mentioned before, some actions need extra parameters. For example, for an import action, you need to define the kind of import:

{
  "file_name": "package.zip",
  "file_size": 1000000,
  "upload_configuration": {
    "name": "ImportPackageConfiguration"
  },
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "package"
    }
  }
}

Perform the upload

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

To perform an upload, send a POST request to the upload URL, containing your file in the body of the request, and your authentication token in the header (x-auth-token).

Finalize the upload

To mark an upload as complete, send a POST request to the endpoint api/v2.0/upload/finalize with the JSON response body received in the first step (request an upload):

{
  "upload_identifier": "<uploadID>",
  "fileIdentifier": "<fileID>"
}
  • upload_identifier: identifier of the upload job.
  • fileIdentifier: identifier of the file in the system.

The structure of a successful response is as follows:

{
    "success": <Boolean>,
    "message": <optional text message>,
    "asset_id": <assetID>,
    "asset_identifier": <assetIdentifier>
}
  • success: status of the upload
  • message: optional error or response message
  • asset_id: numerical value identifying the asset
  • asset_identifier: case-sensitive string identifier of the asset

Can we improve this article ? Provide feedback