logo
logo

Upload API (V2)

The upload API lets you to upload content from other clients 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 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 has 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.

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:

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.

Some actions require 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

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. This generated upload URL is only available for 5 minutes. This is a hard-coded limitation, which means that uploads must be finalized within this 5-minute timeframe.

Example of a file upload using cURL

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 "file=@image.png"

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