Upload API

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.

There are four existing configurations:

{
    "file_name": "<FILENAME>",
    "file_size": <FILE_SIZE>,
    "action": {
        "name": "NewAsset"
    },
    "upload_configuration": {
        "name": "upload_configuration_name"
    }
}

{
    "file_name": "asset.jpg",
    "file_size": 12345,
    "action": {
        "name": "NewAsset"
    },
    "upload_configuration": {
        "name": "AssetUploadConfiguration"
    }
}

{
    "file_name": "<FILENAME>",
    "file_size": <FILE_SIZE>,
    "action": {
        "name": "NewMainFile",
        "parameters": {
            "AssetId": "{the asset id}"
        }
    },
    "upload_configuration": {
        "name": "upload_configuration_name"      
    }
}

{
    "file_name": "asset.jpg",
    "file_size": 12345,
    "action": {
        "name": "NewMainFile",
        "parameters": {
            "AssetId": "40588"
        }
    },
    "upload_configuration": {
        "name": "AssetUploadConfiguration"      
    }
}

{
    "file_name": "<FILENAME>",
    "file_size": <FILE_SIZE>,
    "action": {
        "name": "NewAlternativeFile",
        "parameters": {
            "AssetId": "{the asset id}"
        }
    },
    "upload_configuration": {
        "name": "upload_configuration_name"      
    }
}

{
    "file_name": "asset.jpg",
    "file_size": 12345,
    "action": {
        "name": "NewAlternativeFile",
        "parameters": {
            "AssetId": "40588"
        }
    },
    "upload_configuration": {
        "name": "AssetUploadConfiguration"      
    }
}

{
  "file_name": "<FILENAME>",
  "file_size": <FILE_SIZE>,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Package"
    }
  },
  "upload_configuration": {
    "name": "ImportPackageConfiguration"
  }
}

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

{
  "file_name": "<FILENAME>",
  "file_size": <FILE_SIZE>,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Localization"
    }
  },
  "upload_configuration": {
    "name": "ImportLocalizationsConfiguration"
  }
}

{
  "file_name": "excel.xlsx",
  "file_size": 12345,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Localization"
    }
  },
  "upload_configuration": {
    "name": "ImportLocalizationsConfiguration"
  }
}

{
  "file_name": "<FILENAME>",
  "file_size": <FILE_SIZE>,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Data"
    }
  },
  "upload_configuration": {
    "name": "ImportDataConfiguration"
  }
}

{
  "file_name": "excel.xlsx",
  "file_size": 12345,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Data"
    }
  },
  "upload_configuration": {
    "name": "ImportDataConfiguration"
  }
}

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

{
   "file_name":"<FILENAME>",
   "file_size":"<FILE_SIZE>",
   "upload_configuration":{
      "name":"<UPLOAD_CONFIGURATIION_NAME>",
      "parameters":{
         ...
      }
   },
   "action":{
      "name":"<ACTION_NAME>",
      "parameters":{
         ...
      }
   }
}

A successful response returns the upload URL in the Location header, which is used in the Perform the upload step. This upload URL is returned with the key, name, expiry time, and signature (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 upload URL is valid for five minutes. You can, however, increase the time to a maximum of 1440 minutes (24 hours) by adding upload_url_lifetime_in_minutes to the ConfigurationSettings property in the desired M.UploadConfiguration entity. The upload of all chunks related to the upload request must be finalized before the link expires.

The response also returns a JSON body containing the following information:

{
  "upload_identifier": "<UPLOAD_ID>",
  "file_identifier": "<FILE_ID>"
}

Using the Location header URL from the Request an upload step, create a POST request with the file to upload attached as form-data.

The following example shows a file upload:

curl https://<HOSTNAME>/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_TOKEN>" \
 -H "Content-Type: multipart/form-data" \
 -F "[email protected]"

To finalize the upload, send a POST request to the endpoint api/v2.0/upload/finalize with the JSON response body received in the Request an upload step:

{
  "upload_identifier": "<UPLOAD_ID>",
  "file_identifier": "<FILE_ID>"
}

The structure of a successful response is as follows:

{
    "success": <Boolean>,
    "message": <optional text message>,
    "asset_id": <ASSET_ID>,
    "asset_identifier": <assetIdentifier>
}

The response contains the following:

The following Powershell 7 example shows how an upload script is configured:

$authToken = "Bearer xyz"
$hostName = "https://url.sitecorecontenthub.cloud"

$fileName = "test.jpg"
$filePath = "test.jpg"
$fileSize = 2492578

# create request
$createAssetBody = @{
    file_name = $fileName
    file_size = $fileSize
    upload_configuration = @{
        name = "AssetUploadConfiguration"
    }
    action = @{
        name = "NewAsset"
    }
} | ConvertTo-Json

$createUrl = $hostName + "/api/v2.0/upload"

$createResponse = Invoke-WebRequest -Uri $createUrl -Method 'POST' -Body $createAssetBody -H @{"Authorization" = $authToken; "Content-Type" = "application/json"}

# upload request

$uploadUrl = $createResponse.Headers.Location[0]

$fileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$fileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$fileHeader.Name = $fileName
$fileHeader.FileName = Split-Path -leaf $filePath
$fileContent = [System.Net.Http.StreamContent]::new($fileStream)
$fileContent.Headers.ContentDisposition = $fileHeader
$fileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse("text/plain")

$multipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$multipartContent.Add($fileContent)

Invoke-WebRequest -Body $multipartContent -Method 'POST' -Uri $uploadUrl -Headers @{"Authorization" = $authToken}

$fileStream.Close()

# finalize request

$finalizeUrl = $hostName + "/api/v2.0/upload/finalize"

Invoke-WebRequest -Uri $finalizeUrl -Method 'POST' -Body $createResponse.Content -H @{"Authorization" = $authToken; "Content-Type" = "application/json"}