Last date modified: 2026-Nov-16

Relativity aiR-to-Relativity aiR transfers API

Relativity aiR-to-Relativity aiR transfers help move large volumes of workspaces between Relativity aiR environments faster and with less manual work, saving time and reducing errors.

aiR-to-aiR transfers are possible only between instances of the same environment type, such as an ESUS instance to a CTUS instance from prod-com. Transfers between prod-com and prod-gov are not possible.

Considerations

  • Ensure you have admin level of staging permissions, see Permissions.

  • Both parties must have API/SDK access.
  • The destination directory must exists or be created by the Receiver.
  • The SAS token is never exposed to either party.
  • Cross-region transfers are supported.
  • The workflow is fully operable through the API and ready for custom automation via the API/TransferSDK.

Workflow

The following describes the workflow to automated Relativity aiR-to-Relativity aiR transfer between instances. Receiver refers to the destination instance that will receive the data transfer. Sender refers to the source instance that holds the data to be transferred.

  1. The Receiver generates a reference token pointing to the destination directory. See Creating a reference token.
  2. The reference token is shared with the Sender through a secure out-of-band channel.
  3. Sender validates the token to confirm the destination is as expected.
  4. Sender initiates the transfer request (transfer ID + reference token + source path).
  5. Sender can monitor transfer status through the status endpoint.
  6. The transfer completes on Azure Backbone. No customer machines are involved.

Generating an authorization token

The following section describes how to generate an authorization token separately for the source instance and the destination instance. All endpoints are protected and require an authorization token in the form of a JWT.

  1. Open Relativity aiR.
  2. In the search bar, enter OAuth2 Client.
  3. Create a new OAuth2 client, for more information see, Creating or editing an OAuth2 client.
  4. Copy Client Secret and Client Id on the OAuth2 Client Information page.
  5. The Client Secret may rotate from time to time, which can cause a “400 Bad request - "error": "invalid_client"” error code. Requiring you to enter the new Client Secret in Postman.

  6. Run the curl command in Postman with your Client Secret and Client Id values.
  7. Copy
    curl command:
    curl --location 'YOUR_R1_BASE_ADRESS/Relativity/identity/connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=YOUR_CLIENT_ID' \ --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
    --data-urlencode 'scope=SystemUserInfo'
    Placeholder Description
    YOUR_R1_BASE_ADDRESS The address of Relativity aiR, for example https://esus019064-t044.r1.kcura.com/
    YOUR_CLIENT_ID The Client Id from the OAuth2 System Client
    YOUR_CLIENT_SECRET The Client Secret from the OAuth2 System Client

    Ensure the body of the request is entered correctly. Invalid entries can cause a “400 Bad request - "error": "invalid_client"” error code.

    Copy
    Example response (expire time may differ):
    {
      "access_token": "<access token - copy this value, it is used later>",
      "expires_in": 30758400,
      "token_type": "Bearer",
      "scope": "SystemUserInfo"
    }

    Copy the value of access_token from the response.

Calling Relativity aiR API endpoints

The following section describes calling the Relativity aiR API endpoints:

Requirement Details
Authorization header All endpoints are protected. Add the authorization token to the header. Token scheme is Bearer: Authorization: Bearer YOUR_TOKEN
X-CSRF-Header All endpoints require the X-CSRF-Header header with any value.
HTTP methods POST creates jobs. GET retrieves job details.

Example headers for creating a job:

Endpoint reference

Creating a reference token

The following section describes how to use POST to create a reference token. Send a POST request with a URL in the following format:

Copy
https://{destination_instance_url}/transfer-service/api/v2/transfer/reference-token
Body field Description
DestinationPath Relativity fileshare path to directory, where data should be placed.
Copy
Example request:
{
  "DestinationPath": "\\\\files.t081.esus019064.r1.kcura.com\\T081\\StructuredData\\DestDir"
}
Copy
Example response:
{
  "referenceToken": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJ0ZW5hbnRJZCI6IlQwODEiLCJwb2RJZCI6ImVzdXMwMTkwNjQiLCJqdGkiOiI1M2FjNzE5Ny0xOGQyLTRlNGYtYTYwNy1iZGQzZGY3ZDEyM2IiLCJuYmYiOjE3ODAwNTgzMDQsImV4cCI6MTc4MDY1OTUwNH0."
}

Validating a reference token

Reference tokens can be validated by either party, but revoked only by the Receiver.

The following section describes how to use POST to create validate a reference token. Send a POST request with a URL in the following format:

Copy
https://{source_instance_url}/transfer-service/api/v2/transfer/reference-token/validate
Field Description
ReferenceToken Token representing destination directory, returned during reference token creation
Copy
Example request:
{
  "referenceToken": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJ0ZW5hbnRJZCI6IlQwODEiLCJwb2RJZCI6ImVzdXMwMTkwNjQiLCJqdGkiOiI1M2FjNzE5Ny0xOGQyLTRlNGYtYTYwNy1iZGQzZGY3ZDEyM2IiLCJuYmYiOjE3ODAwNTgzMDQsImV4cCI6MTc4MDY1OTUwNH0."
}
Copy
Example response:
{
  "isValid": true,
  "customerName": "Relativity",
  "referenceToken": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJ0ZW5hbnRJZCI6IlQwODEiLCJwb2RJZCI6ImVzdXMwMTkwNjQiLCJqdGkiOiI1M2FjNzE5Ny0xOGQyLTRlNGYtYTYwNy1iZGQzZGY3ZDEyM2IiLCJuYmYiOjE3ODAwNTgzMDQsImV4cCI6MTc4MDY1OTUwNH0."
}

Revoking a reference token

The reference token is revoked automatically once the transfer is completed successfully. If the transfer failed or is canceled the revoke needs to be done manually.

The following section describes how to use POST to revoke a reference token. Send a POST request with a URL in the following format:

Copy
https://{destination_instance_url}/transfer-service/api/v2/transfer/reference-token/revoke
Field Description
ReferenceToken Token representing destination directory, returned during reference token creation
Copy
Example request:
{
  "referenceToken": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJ0ZW5hbnRJZCI6IlQwODEiLCJwb2RJZCI6ImVzdXMwMTkwNjQiLCJqdGkiOiI1M2FjNzE5Ny0xOGQyLTRlNGYtYTYwNy1iZGQzZGY3ZDEyM2IiLCJuYmYiOjE3ODAwNTgzMDQsImV4cCI6MTc4MDY1OTUwNH0."
}

A reference token is the representation of a SAS token outside Relativity. Creating a reference token creates a SAS token that is valid for 7 days. The transfer must finish within that time.

Creating a transfer

The following section describes how to use POST to create a transfer. Send a POST request with a URL in the following format:

Copy
https://{source_instance_url}/transfer-service/api/v2/transfer/jobs
Field Description
TransferJobID Job GUID
ReferenceToken Token representing destination directory, returned during reference token creation
SourcePath Relativity fileshare path to directory, that contains the data to transfer.
Copy
Example body:
{
  "TransferJobID": "2c48b3eb-7375-4e1e-8ce4-2763b61ef1f1",
  "ReferenceToken": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJ0ZW5hbnRJZCI6IlQwODEiLCJwb2RJZCI6ImVzdXMwMTkwNjQiLCJqdGkiOiI1M2FjNzE5Ny0xOGQyLTRlNGYtYTYwNy1iZGQzZGY3ZDEyM2IiLCJuYmYiOjE3ODAwNTgzMDQsImV4cCI6MTc4MDY1OTUwNH0",
  "SourcePath": "\\\\files.t044.esus019064.r1.kcura.com\\T044\\StructuredData\\SourceDir",
}

Getting transfer details

The following section describes how to use GET to transfer details. Send a GET request with a URL in the following format:

Copy
https://{source_instance_url}/transfer-service/api/v2/transfer/jobs/{transferJobId}
Copy
Example response:
{
  "transferStatus": "InProgress",
  "transferJobID": "2c48b3eb-7375-4e1e-8ce4-2763b61ef1f1",
  "referenceToken": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJ0ZW5hbnRJZCI6IlQwODEiLCJwb2RJZCI6ImVzdXMwMTkwNjQiLCJqdGkiOiI1M2FjNzE5Ny0xOGQyLTRlNGYtYTYwNy1iZGQzZGY3ZDEyM2IiLCJuYmYiOjE3ODAwNTgzMDQsImV4cCI6MTc4MDY1OTUwNH0.",
  "sourceFullPath": "\\\\files.t044.esus019064.r1.kcura.com\\T044\\StructuredData\\SourceDir",
  "tags": {},
  "eta": null,
  "transferStatistics": {
    "successfulFiles": 0,
    "failedFiles": 0,
    "skippedFiles": 0,
    "successfulBytes": 0,
    "failedBytes": 0,
    "skippedBytes": 0,
    "successfulEmptyDirectories": 0,
    "failedEmptyDirectories": 0,
    "skippedEmptyDirectories": 0
  },
  "enumerationStatistics": {
    "totalFiles": 8826,
    "totalSize": 30100492,
    "totalEmptyDirectories": 0,
    "status": "inprogress",
    "error": null
  },
  "transferType": "R1toR1"
}

Canceling a transfer

The following section describes how to use DELETE to cancel a transfer. Send a DELETE request with a URL in the following format:

Copy
https://{source_instance_url}/transfer-service/api/v2/transfer/jobs/{transferJobId}

Error codes

For more information on possible error codes, see Relativity Transfer Service documentation.

Feedback