- Include the JWT in the request header
Item Transfer API (3.0)
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. In this primary workflow, source files are read from Azure Blob Storage.
Alternatively, you can use the Item Transfer API to upload 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.
The Item Transfer API covers the destination side of a content migration. Before using this API, complete all steps in the Content Transfer API to generate .raif files in the destination environment.
Return the list of available blob sources 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 source 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.
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 until TransferState is Finished. If TransferState is Failed, retry the transfer.
If BlobState is TransferredWithErrors, this is a terminal state indicating a partial success. To investigate, retrieve the transfer details and review the ValidationErrors list.
You can also retrieve the details of a specific transfer or view the transfer history.
After the transfer is finished, delete the blob source to remove the .raif file from Azure Blob Storage.
This completes the migration process.
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
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.
- In the Sitecore Cloud Portal, open SitecoreAI Deploy.
- Click Credentials > Environment > Create credentials > Automation.
- Fill out the automation client details, then click Create.
- 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.
Run the following cURL command to request a JWT. Replace the placeholder values with your client ID and client secret.
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.