---
title: "Upload"
slug: "upload"
abstract: "How to use the Upload API (V2), and overview of the upload process."
---
# Upload

The Upload API (V2) lets you upload content from clients other than the Sitecore Content Hub web UI.

[Access the OpenAPI definition of the latest version of the Upload API](https://api-docs.sitecore.com/ch/upload-api)

> [!important]
> The Upload API is not intended for the bulk upload of assets. High volumes of parallel uploads can impact performance. Review [Performance](https://doc.sitecore.com/ch/en/users/content-hub/performance.html) best practices to ensure optimal performance of Sitecore Content Hub.

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](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload-large-files.html "Upload large files"). To change the time period that the upload URL is available, see [Change upload URL lifetime](https://doc.sitecore.com/ch/en/developers/cloud-dev/update-the-configuration-settings.html "Update the configuration settings").

## 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.

### 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. |

There are four existing configurations:

### AssetUploadConfiguration

This sample payload uploads an asset.

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

```

Request example:

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

```

This sample payload uploads a new version of an asset.

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

```

Request example:

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

```

This sample payload uploads an alternative thumbnail for an asset.

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

```

Request example:

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

```

### ImportPackageConfiguration

This sample payload imports a package.

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

```

Request example:

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

```

### ImportLocalizationsConfiguration

This sample payload imports a localization file.

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

```

Request example:

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

```

### ImportDataConfiguration

This sample payload imports data from an Excel file.

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

```

Request example:

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

```

## The upload process

The upload process consists of three steps:

1. [Request an upload](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html#UUID-62588c53-1905-f0c7-90a0-b614b7b804bd_N1728318736067 "Request an upload")
2. [Perform the upload](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html#UUID-62588c53-1905-f0c7-90a0-b614b7b804bd_N1728318764248 "Perform the upload")
3. [Finalize the upload](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html#UUID-62588c53-1905-f0c7-90a0-b614b7b804bd_N1728318777667 "Finalize the upload")

## Request an upload

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

- `file_name` - *name* of the file to upload.
- `file_size` - *size* of the file to upload.
- `upload_configuration` - upload configuration.
- `action` - actions to perform on the file.

```json
{
   "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](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html#UUID-62588c53-1905-f0c7-90a0-b614b7b804bd_N1728318764248 "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` - *identifier* of the upload job.
- `file_identifier` - *identifier* of the file in the system.

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

```

## Perform the upload

Using the `Location` header URL from the [Request an upload](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html#UUID-62588c53-1905-f0c7-90a0-b614b7b804bd_N1728318736067 "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
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 "file=@image.png"

```

## Finalize the upload

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](https://doc.sitecore.com/ch/en/developers/cloud-dev/upload.html#UUID-62588c53-1905-f0c7-90a0-b614b7b804bd_N1728318736067 "Request an upload") step:

- **upload_identifier** - *identifier* of the upload job.
- **file_identifier** - *identifier* of the file in the system.

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

```

The structure of a successful response is as follows:

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

```

The response contains the following:

- **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

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

```powershell
$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"}

```