# Item Transfer API

The Item Transfer API allows administrators to incorporate special files (*sources*) containing migrated content and media data into the database of the destination environment. Sources can come from the file system or Azure Blob Storage.

The Item Transfer API consumes `.raif` files created using the [Content Transfer API](https://api-docs.sitecore.com/sai/content-transfer). Each file represents a single data tree from the source environment, and each tree is either a single item or an item plus all of its descendants.

You can also [upload](#operation/startItemsTransfer) small `.raif` files (less than 50 MB) directly to blob storage, but for large content migrations between environments, use the **Content Transfer API**, which uses chunked streaming to produce `.raif` files in the destination environment automatically.

You can also use this API to explore and validate sources, fetch details about a specific source, examine a history of consumed sources, retry failed sources, and discard sources you no longer need.

# Base URL
In the base URL, replace `{host}` with your environment host name. Find the value in SitecoreAI Deploy > **Projects** > your project > **Authoring environments** > your environment > **Details** > **Environment host name**. 


# Authorization
To authorize your requests, use environment automation client credentials and generate a JSON Web Token (JWT).

Note: To create client credentials, you must be an [Organization Admin or Organization Owner](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html).

## Create an automation client
1. In the Sitecore Cloud Portal, open SitecoreAI Deploy.
2. Click **Credentials** > **Environment** > **Create credentials** > **Automation**.
3. Fill out the automation client details, then click **Create**.
4. Copy the client ID and the client secret because you won't be able to view them again in SitecoreAI Deploy. You'll use them to request a JWT.

## Request a JWT

Run the following cURL command to request a JWT. Replace the placeholder values with your client ID and client secret.
```curl
  curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.sitecorecloud.io'
```

The JWT expires in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new JWT by repeating this `POST` request.

We recommend that you cache the JWT for 24 hours to avoid repeating this `POST` request while the JWT is still valid.

## Include the JWT in the request header

You can now start making REST API requests. You must include the JWT in the request header of every request. For example:
```curl
  curl -X GET '{YOUR_BASE_URL}/...' \
  -H 'Authorization: Bearer {YOUR_JWT}' \
  -H 'Accept: application/json'
```


Version: 3.0
Metadata:
  - product: SitecoreAI

## Servers

```
https://{host}/sitecore/shell/api/v3/ItemsTransfer
```

Variables:
- `host`: The environment host name
Default: "cm.your-tenant.sitecorecloud.io"

## Security

### bearerAuth

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Item Transfer API](https://api-docs.sitecore.com/_bundle/sai/item-transfer/index.yaml)

## Transfers

Operations related to managing and monitoring item transfers.

### Returns the status of consumed and transferred sources

 - [GET /transfers](https://api-docs.sitecore.com/sai/item-transfer/transfers/gettransfers.md): Returns a paged list of currently available active and completed transfers across all Sitecore databases.
Each entry includes original file name, transfer date, and transfer state.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/transfers?page=1&pageSize=50

### Retrieves the details of a loaded to memory transferred source by transferId

 - [GET /transfers/{transferId}](https://api-docs.sitecore.com/sai/item-transfer/transfers/gettransferbyid.md): Retrieves the detailed metrics about items count, state, errors, and validation warnings for an actively transferring or completed source.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/transfers/consumed.20260622%20123617%203195348.14f58964-9a2f-42fb-8b6d-62440df23454

### Starts consuming a file or blob source into a database

 - [POST /transfers/databases/{databaseName}/sources](https://api-docs.sitecore.com/sai/item-transfer/transfers/startitemstransfer.md): Initiates the content transfer from a local Sitecore file system source or Azure Blob storage into the target database.

Examples:
POST /sitecore/shell/api/v3/ItemsTransfer/transfers/databases/master/sources?fileName=testFile.raif
POST /sitecore/shell/api/v3/ItemsTransfer/transfers/databases/master/sources?blobName=content_2025-08-28.raif

### Retries the transfer of a failed source for a specific database by re-queuing it for processing

 - [PUT /transfers/databases/{databaseName}/sources](https://api-docs.sitecore.com/sai/item-transfer/transfers/retryfaileditemstransfer.md): Retries a failed attempt to transfer a source file into a database. Only sources with a transfer state of "Failed" can be retried.

Example:
PUT /sitecore/shell/api/v3/ItemsTransfer/transfers/databases/master/sources/content_2025-08-28.raif

## Items

Operations for viewing details of specific transferred items.

### Returns a paginated list of transferred items for a specific database and source

 - [GET /transfers/databases/{databaseName}/sources/{sourceName}/items](https://api-docs.sitecore.com/sai/item-transfer/items/gettransferreditems.md): Provide the required databaseName and sourceName of an ongoing or completed transfer.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/transfers/databases/master/sources/consumed.20260622%20123617%203195348.14f58964-9a2f-42fb-8b6d-62440df23454/items?page=1&pageSize=50

### Retrieves the details of a specific transferred item for a given database and source

 - [GET /transfers/databases/{databaseName}/sources/{sourceName}/items/{itemId}](https://api-docs.sitecore.com/sai/item-transfer/items/gettransferreditemdetails.md): Given a particular itemId within an active sourceName into a databaseName, returns all captured metadata and corresponding localized or versioned field information.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/transfers/databases/master/sources/consumed.20260622%20123617%203195348.14f58964-9a2f-42fb-8b6d-62440df23454/items/11111111-1111-1111-1111-111111111111

## Sources

Operations for managing file and blob storage sources for transfers.

### Returns a paginated list of blob sources available in the system

 - [GET /sources/blobs](https://api-docs.sitecore.com/sai/item-transfer/sources/getblobsources.md): Retrieves the list of available blob sources from Azure Blob Storage which have not yet been deleted or permanently archived.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/sources/blobs?page=1&pageSize=50

### Retrieves the state of a specific blob source

 - [GET /sources/blobs/{blobName}](https://api-docs.sitecore.com/sai/item-transfer/sources/getblobsourcestate.md): Returns HTTP 200 containing BlobDetailsResult containing the state of the blob source.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/sources/blobs/content_2025-08-28.raif

### Uploads a blob to the system for processing

 - [POST /sources/blobs/{blobName}](https://api-docs.sitecore.com/sai/item-transfer/sources/uploadblobsource.md): Note that the file data is pushed using stream content chunks. Set query parameter gzip to true if stream applies gzip algorithms.

Example:
POST /sitecore/api/v3/ItemsTransfer/sources/blobs/content_2025-08-28.raif?gzip=true

### Discards a transferred source by deleting its associated file or blob

 - [DELETE /sources/blobs/{blobName}](https://api-docs.sitecore.com/sai/item-transfer/sources/deleteblobsource.md): Performs the permanent removal of artifacts tracking across Blob storage and caches representing the passed source.

Example:
DELETE /sitecore/shell/api/v3/ItemsTransfer/sources/blobs/content_2025-08-28.raif

### Lists file sources

 - [GET /sources/files](https://api-docs.sitecore.com/sai/item-transfer/sources/getfilesources.md): Returns all file sources natively accessible by the CMS, with optional support for paginated tracking.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/sources/files?page=1&pageSize=50

## History

Access to historical records of item transfers.

### Retrieves a paginated history of consumed sources across all databases

 - [GET /history](https://api-docs.sitecore.com/sai/item-transfer/history/gettransfershistory.md): Returns the complete transition timeline of each transfer in descending order by ConsumeDate. Useful for inspecting historical runs.

Example:
GET /sitecore/shell/api/v3/ItemsTransfer/history?page=1&pageSize=50