Upload API (V2)

The upload API lets you upload content from clients other than 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/process - performs the request.

  • api/v2.0/upload/finalize - finalizes the upload.

Note

To upload files larger than 10 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 has the following structure:

RequestResponse

{
   "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:

RequestResponse

{
  "upload_identifier": "<uploadID>",
  "file_identifier": "<fileID>"
}

  • upload_identifier - identifier of the upload job.

  • file_identifier - identifier of the file in the system.

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.

Note

The maximum allowed file size parameter limits the size of files allowed for upload with an upper Azure blob limit of 4.7 TB.

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:

Action

Description

NewAsset

Creates a new asset and sets the uploaded file as the main file for the newly created asset.

NewMainFile

Changes the main file with the uploaded file for an existing asset; requires the AssetId action parameter to specify which asset must be updated.

NewAlternativeFile

Changes the alternative file with the uploaded file for an existing asset; requires the AssetId action parameter to specify which asset must be updated.

Import

Considers the uploaded file as an import and executes an import job for it.

Some actions require extra parameters. For example, for an import action, you need to define the kind of import:

RequestResponse

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

Perform the upload

To perform an upload, send a POST request to the upload URL, containing your file with the key file as form-data, and your authentication token in the header.

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. By default, the generated upload URL is valid for 5 minutes, however it can be increased to a maximum of 1440 minutes (24 hours) by adding upload_url_lifetime_in_minutes to the ConfigurationSettings property of the desired M.UploadConfiguration entity. The upload of all chunks related to the upload request must be finalized before the link expires.

Example of a file upload using cURL

RequestResponse

curl https://{CONTENT_HUB_HOST}/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 \
 -H "Authorization: Bearer {ACCESS_TOKEN}" \
 -H "Content-Type: multipart/form-data" \
 -F "[email protected]"

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):

RequestResponse

{
  "upload_identifier": "<uploadID>",
  "file_identifier": "<fileID>"
}

  • upload_identifier - identifier of the upload job.

  • file_identifier - identifier of the file in the system.

The structure of a successful response is as follows:

RequestResponse

{
    "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

Do you have some feedback for us?

If you have suggestions for improving this article,