# Item Transfer API The Item Transfer API allows SitecoreAI *Organization Admins* and *Organization Owners* to incorporate special files (*sources*) containing migrated content and media data into the database of the *destination* environment. The Item Transfer API is primarily used to consume `.raif` files produced by the [Content Transfer API](https://api-docs.sitecore.com/sai/content-transfer). In this primary workflow, source files are read from Azure Blob Storage. Alternatively, you can use the Item Transfer API to [upload](#operation/uploadBlobSource) small `.raif` files (under 100 MB) from your Sitecore file system, but this is a secondary workflow intended for smaller or ad hoc transfers. For large content migrations between environments, use the Content Transfer API to generate `.raif` files via chunked streaming, and then consume them using the Item Transfer API. Each `.raif` 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. Note the following: - To use this REST API, you must authorize your API requests. - You must be an *Organization Admin* or *Organization Owner* to use this API. - Unlike the Content Transfer API, the Item Transfer API is used only in your *destination* environment, not in your *source* environment. # Migrating content The Item Transfer API covers the *destination* side of a content migration. Before using this API, complete all steps in the [Content Transfer API](https://api-docs.sitecore.com/sai/content-transfer) to generate `.raif` files in the destination environment. Also ensure you have the *Organization Admin* or *Organization Owner* role, and that you have determined your *destination* [base URL](#section/base-url) and created a [JWT](#section/authorization) for the environment. ## Verify the blob is available [Return the list of available blob sources](#operation/getBlobSources) to confirm that the `.raif` file produced by the Content Transfer API is present and has a `BlobState` of `Uploaded`, which means that the file is ready to consume. ## Start consuming the blob [Start consuming the source](#operation/startItemsTransfer) into the destination database, passing the `.raif` file name as the `blobName` parameter. Transferred items are immediately available to work with in the destination environment while the system completes the sync to the database in the background. The `location` response header contains a URL. The final path segment of the URL is the transfer ID used in subsequent requests. ## Monitor the transfer Although items are available immediately, poll the transfer status to detect failures. If the background sync fails before completing, items that were not yet synced will become unavailable and the transfer must be retried. [Poll the transfer status](#operation/getTransfers) until `TransferState` is `Finished`. If `TransferState` is `Failed`, [retry the transfer](#operation/retryFailedItemsTransfer). If `BlobState` is `TransferredWithErrors`, this is a terminal state indicating a partial success. To investigate, [retrieve the transfer details](#operation/getTransferById) and review the `ValidationErrors` list. You can also [retrieve the details of a specific transfer](#operation/getTransferById) or [view the transfer history](#operation/getTransfersHistory). ## Clean up After the transfer is finished, [delete the blob source](#operation/deleteBlobSource) to remove the `.raif` file from Azure Blob Storage. This completes the migration process. # Base URL In the base URL, replace `{host}` with your environment host name of your *destination* environment (where you're migrating data to). Find the environment host name in SitecoreAI Deploy > **Projects** > your project > **Authoring environments** > your environment > **Details** > **Environment host name**. Example environment host name: `your-environment.sitecorecloud.io` # 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 `403 Forbidden`, 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 License: closed source Metadata: - product: SitecoreAI ## Servers ``` https://{host}/sitecore/shell/api/v3/ItemsTransfer ``` Variables: - `host`: The environment host name. Default: "your-environment.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-api/index.yaml) ## Transfers Operations related to managing and monitoring item transfers. ### Return the status of consumed and transferred sources - [GET /transfers](https://api-docs.sitecore.com/sai/item-transfer-api/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. ### Retrieve the details of a transferred source - [GET /transfers/{transferId}](https://api-docs.sitecore.com/sai/item-transfer-api/transfers/gettransferbyid.md): Retrieves the detailed metrics about items count, state, errors, and validation warnings for an actively transferring or completed source. ### Start consuming a file or blob source into a database - [POST /transfers/databases/{databaseName}/sources](https://api-docs.sitecore.com/sai/item-transfer-api/transfers/startitemstransfer.md): Starts a content transfer from Azure Blob storage or a local Sitecore file system source into the target database. Primary workflow: Use blobName to consume .raif files produced by the Content Transfer API from Azure Blob Storage. Example: blobName=content-transfer-12345678-1234-1234-1234-123456789abc.raif Secondary workflow for small, ad hoc scenarios: Use fileName only when consuming a .raif file from the local Sitecore file system. Example: fileName=testFile.raif Provide either blobName or fileName, not both. In the response, the location header contains the full path to the consumed source in the destination environment. The final path segment following the final slash is the blob name or file name: https://my-environment.sitecorecloud.io/sitecore/shell/api/v3/ItemsTransfer/sources/blobs/{BlobNameOrFileName} You will use the blob name or file name in other endpoints. For example, when you retrieve the details of a transferred source. ### Retry the transfer of a failed source for a specific database by re-queuing it for processing - [PUT /transfers/databases/{databaseName}/sources/{sourceName}](https://api-docs.sitecore.com/sai/item-transfer-api/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. ## Items Operations for viewing details of specific transferred items. ### Return 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-api/items/gettransferreditems.md): Returns a paginated list of items for an ongoing or completed transfer in the specified database. Provide the required databaseName and sourceName of an ongoing or completed transfer. ### Retrieve 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-api/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. ## Sources Operations for managing file and blob storage sources for transfers. ### Return a paginated list of blob sources available in the system - [GET /sources/blobs](https://api-docs.sitecore.com/sai/item-transfer-api/sources/getblobsources.md): Retrieves the list of available blob sources from Azure Blob Storage that have not yet been deleted or permanently archived. ### Retrieve the state of a specific blob source - [GET /sources/blobs/{blobName}](https://api-docs.sitecore.com/sai/item-transfer-api/sources/getblobsourcestate.md): Returns the current upload and processing state of a specific blob source. Use this to poll the blob's state after uploading. ### Upload a blob to the system for processing - [POST /sources/blobs/{blobName}](https://api-docs.sitecore.com/sai/item-transfer-api/sources/uploadblobsource.md): Uploads a blob. Note that the file data is pushed using stream content chunks. The file size must be less than 100 MB. Set the gzip query parameter to true if the stream applies gzip algorithms. ### Discard a transferred source by deleting its associated file or blob - [DELETE /sources/blobs/{blobName}](https://api-docs.sitecore.com/sai/item-transfer-api/sources/deleteblobsource.md): Permanently removes the artifacts across the blob storage and caches representing the passed source. ### List file sources - [GET /sources/files](https://api-docs.sitecore.com/sai/item-transfer-api/sources/getfilesources.md): Returns all file sources natively accessible by SitecoreAI CMS, with optional support for paginated tracking. ## History Access historical records of item transfers. ### Retrieve a paginated history of consumed sources across all databases - [GET /history](https://api-docs.sitecore.com/sai/item-transfer-api/history/gettransfershistory.md): Returns the complete transition timeline of each transfer in descending order by ConsumeDate. Useful for inspecting historical runs.