Staging Reports API (REST)

Staging Insights API

The Staging Reports API (also known as the Staging Insights API) provides a REST service that allows you to generate folder and file reports about tenant data stored in staging areas. This guide will help you get started with the API, including making your first requests, understanding the available endpoints, and authenticating your API calls.

With this API you can:

• Enumerate folders in staging containers.
• Generate folder or file reports from staging data.
• Retrieve lists of submitted reports.
• Retrieve generated reports as downloadable files.

• Access billable summary reports for contracted staging allowance tracking.

The service accepts and returns JSON-encoded requests and uses standard HTTP response codes, authentication, and verbs.

Resources

• Staging Reports REST API V3 Reference
• Staging Reports REST API V4 Reference

Permissions

The account used to access the Staging Reports API requires the View Admin Repository instance permission and one of the following permissions:

• View Client Domain Staging Reports
  • Allows users to create Staging Reports for staging containers/fileshares they have access to.
  • With this permission, the account must be assigned to the specific fileshares they want to access. See Granting user access to specific fileshares for details in the procedure.
  • This permission is suitable for users who need to generate reports for specific client domains or tenant data.
• View Instance-wide Staging Reports
  • Allows users to create Staging Reports across all staging containers/fileshares in the instance.
  • With this permission, the account's assignment to specific fileshares is not checked.
  • This permission is ideal for administrators, finance team members, or API accounts that need comprehensive access for billing and monitoring purposes.

See Setting instance permissions in the RelativityOne User Guide for the procedure to set permissions.

Considerations

• When the parameter UseSnapshot is set to false, you cannot run reports on top level folders (e.g. t019/ARM/), but only from 2nd level onward (e.g. t019/ARM/1017587_WS2_20191223215604 or subsequently-nested folders)
• Review the considerations described in the Staging Reports topic, since these considerations apply when using the API as well.

URLs

The URLs for the REST API endpoints use the tenant URL format with version **v4**:

1
<host>/Relativity.Rest/API/staging-insights/v4/

RelativityOne REST API Authentication

To access the Staging Reports API, you must authenticate your requests. For more information on authentication methods, see RelativityOne REST API Authentication.

Bearer Token Authentication

You can connect to the REST services using bearer token authentication. When using bearer token authentication, clients access the service with an access token issued by the Relativity identity service based on a consumer key and secret obtained through an OAuth2 client.

Steps to Authenticate Using Bearer Token

1. Create a Relativity OAuth2 Client:
   1. Navigate to the OAuth2 Client Manager in RelativityOne:
      1. Go to Home > Authentication > OAuth2 Client Manager.
   2. Click New OAuth2 Client to create a new client, or click Edit next to an existing client to modify it.
   3. Complete the fields on the form. Fields in orange are required:
      1. Name: Enter a unique name for the OAuth2 client.
      2. Enabled: Indicate whether the client will have access to Relativity.
      3. Flow Grant Type: Select Client Credentials.
      4. Context User: Select a user who is a member of the Relativity Administrators group.
      5. Access Token Lifetime: Set the duration (in minutes) for which access tokens are valid. The recommended value is 60 minutes.
   4. Click Save to create the OAuth2 client.
   5. For more information, see OAuth2 clients on the RelativityOne Documentation site.
2. Obtain a Bearer Token: Send a POST request to the token endpoint with your credentials.
   Copy

   curl -X POST "<host>/Relativity/Identity/connect/token" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "grant_type=client_credentials" \
        -d "scope=SystemUserInfo"
        -d "client_id=<your_client_id>" \
        -d "client_secret=<your_client_secret>" \

3. Use the Bearer Token: Include the obtained token in the Authorization header of your API requests.
   Copy

   curl -X GET "<host>/relativity.rest/api/staging-insights/v4/Directory/containers" \
        -H "Authorization: Bearer your_access_token"

Rate Limiting

To ensure fair usage and maintain the stability of our services, we implement rate limiting on our API endpoints. This means there's a restriction on the number of requests you can make within a given timeframe.

Currently, you're allowed to send 65 requests per 60-second.

When you exceed the allowed request limit, your requests will be temporarily blocked, and you'll receive an HTTP 429 Too Many Requests status code.

Postman sample file

You can use a Postman sample file to become familiar with making calls to endpoints on the service. Download the sample file from Staging Inisghts API Postman file.

To get started with Postman, complete these steps:

1. Obtain access to a Relativity environment. You need a username and password to make calls to your environment.
2. Install Postman.
3. Import the Postman sample file for the service. For more information, see Working with data files on the Postman web site.
4. Select an endpoint. Update the URL with the domain for your Relativity environment and any other variables.
5. In the Authorization tab, set the Type to Basic Auth, enter your Relativity credentials, and click Update Request.
6. See the following sections on this page for more information on setting required fields for a request.
7. Click Send to make a request.

API Endpoints/Operations

Get containers

To retrieve available staging containers (tenant data storage areas), send a GET request with the following URL format:

1
<host>/relativity.rest/api/staging-insights/v4/Directory/containers

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "containers": [
    {
      "containerName": "t021"
    },
    {
      "containerName": "t021a"
    },
    {
      "containerName": "t030"
    }
  ]
}

List Directories

To list directories within a staging container path, send a POST request with the following URL format and request body::

1
<host>/Relativity.Rest/API/staging-insights/v4/directory/directories

1
2
3
4
5
6
7
{
  "path": "t021/ARM/Test",
  "paging": {
    "start": 1,
    "limit": 300
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "path": "t021/ARM/Test",
  "dirs": [
    "t021/ARM/Test/Folder-1",
    "t021/ARM/Test/Folder-2",
    "t021/ARM/Test/ProcessedData",
    "t021/ARM/Test/Archives"
  ],
  "paging": {
    "start": 1,
    "limit": 300
  }
}

Generate New Report

To generate a new staging report, send a POST request with the following URL format and request body:

1
<host>/Relativity.Rest/API/staging-insights/v4/reports

1
2
3
4
5
6
{
  "path": "t021/ARM/Test",
  "useSnapshot": false,
  "includeFiles": false,
  "depth": "TwoLevelsDeep"
}

1
2
3
4
5
6
{
  "path": "t021/ARM/Test",
  "useSnapshot": false,
  "includeFiles": false,
  "depth": 2
}

The depth parameter accepts the following values (as string or integer):

• TopLevelOnly or 0: Report only the top-level directory
• OneLevelDeep or 1: Include one level of subdirectories
• TwoLevelsDeep or 2: Include two levels of subdirectories
• FullHierarchy or -1: Include the complete directory hierarchy

1
2
3
{
  "reportId": "159b1276-8c12-4ac1-b58b-fb4dc656dd89"
}

List reports

To list all reports, send a GET request with the following URL format::

1
<host>/relativity.rest/api/staging-insights/v4/Reports?start={{start}}&limit={{limit}}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "reportJobs": [
    {
      "reportId": "bae8dadf-c5b3-4d86-abfc-cce9f49455b7",
      "path": "t021/ARM/TestFolder-1",
      "createdOn": "2023-11-17T14:21:35.2681337Z",
      "state": "Succeeded",
      "includeFiles": false,
      "useSnapshot": false,
      "depth": "TopLevelOnly"
    },
    {
      "reportId": "e3f1bd73-a578-4e86-a423-f4340b0a1f0d",
      "path": "t021/ARM/TestFolder-200",
      "createdOn": "2023-11-17T14:20:47.9840466Z",
      "state": "Processing",
      "includeFiles": true,
      "useSnapshot": false,
      "depth": "FullHierarchy"
    }
  ],
  "paging": {
    "start": 1,
    "limit": 200
  }
}

Get report file

To retrieve a generated report file, send a GET request with the following URL format:

1
<host>/Relativity.Rest/API/staging-insights/v4/reports/{{reportId}}/file

Response:
Returns the generated report file as a downloadable CSV or other formatted file.

Cancel report

To cancel a specific report, send a DELETE request with the following URL format:

1
<host>/Relativity.Rest/API/staging-insights/v4/reports/{reportId}

1
true

Get billable summary reports

The billable summary report is a pre-formatted CSV containing a directory list of all folders, at three levels of depth, that count towards the contracted staging allowance.

To retrieve a billable summary report file, send a GET request with the following URL format:

1
<host>/relativity.rest/api/staging-insights/v4/billable-summary-reports/file?container={{container}}&date={{date}}

Date should be in YYYYMMDD format.

Response:
Returns a CSV file containing the billable summary data.

Get billable summary report list

To retrieve a list of available billable summary reports, send a GET request with the following URL format:

<host>/relativity.rest/api/staging-insights/v4/billable-summary-reports?start={{start}}&limit={{limit}}

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "reports": [
    {
      "container": "t021",
      "date": "2023-11-17T14:21:35.2681337Z"
    },
    {
      "container": "t021a",
      "date": "2023-11-17T14:20:47.9840466Z"
    }
  ],
  "totalCount": 2
}

PowerShell Code Samples for Staging Reports

Set variables

Use values from your environment

$relativityHost = "<host>"
$clientId = "XXX"
$clientSecret = "XXX"

Obtain Access Token

Use the following PowerShell script to authenticate and retrieve an access token.

1
2
3
4
5
6
7
8
9
10
11
12
#Define headers, Uri and body for authentication
$tokenHeaders = @{
    'Content-Type' = 'application/x-www-form-urlencoded'
}
$tokenUri = "$relativityHost/Relativity/Identity/connect/token"
$tokenBody = "grant_type=client_credentials&client_id=$clientId&client_secret=$clientSecret&scope=SystemUserInfo"

#Request access token
$accessToken = Invoke-RestMethod -Uri $tokenUri -Headers $tokenHeaders -Body $tokenBody -Method POST

#Extract the token (only the access token, not the full response)
$token = $accessToken.access_token

Set Headers and Uri for Staging Reports

These headers are used specifically for making requests to the Staging Reports API.

1
2
3
4
5
$headersToUseWithStagingReports = @{
  Authorization = "Bearer $token"
  'Content-Type' = "application/json"
}
$requestUri = "$relativityHost/relativity.rest/api/staging-insights/v4"

Retrieve Containers

Send a GET request to fetch available staging containers.

1
2
3
4
# Send request to fetch containers
$containersResponse = Invoke-RestMethod -Uri "$requestUri/Directory/containers" -Method GET -Headers $headersToUseWithStagingReports
# Convert and display the response as JSON
$containersResponse | ConvertTo-Json

List Directories

Send a POST request to list directories within a specific staging container path.

1
2
3
4
5
6
7
8
9
10
11
12
# Define the request body for directory listing
$directoryListBody = @{
    path = "t021/ARM/Test"
    paging = @{
        start = 1
        limit = 300
    }
} | ConvertTo-Json -Depth 3
# Send request to list directories
$directoriesResponse = Invoke-RestMethod -Uri "$requestUri/Directory/directories" -Method POST -Headers $headersToUseWithStagingReports -Body $directoryListBody
# Display the response
$directoriesResponse | ConvertTo-Json

Generate a New Report

Send a POST request to generate a new staging report.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Define the request body for report generation (using string value)
$reportRequestBody = @{
    path = "t021/ARM/Test"
    useSnapshot = $false
    includeFiles = $false
    depth = "TwoLevelsDeep"
} | ConvertTo-Json -Depth 3

# Define the request body for report generation (using integer value)
$reportRequestBodyWithInt = @{
    path = "t021/ARM/Test"
    useSnapshot = $false
    includeFiles = $false
    depth = 2
} | ConvertTo-Json -Depth 3

# Send request to generate report
$reportResponse = Invoke-RestMethod -Uri "$requestUri/Reports" -Method POST -Headers $headersToUseWithStagingReports -Body $reportRequestBody

List All Reports

Send a GET request to fetch all staging reports.

1
2
3
4
5
# Send request to fetch reports
$reportsResponse = Invoke-RestMethod -Uri "$requestUri/Reports?start=1&limit=200" -Method GET -Headers $headersToUseWithStagingReports

# Convert and display the response as JSON
$reportsResponse | ConvertTo-Json -Depth 3

Get Specific Report File

Send a GET request to download a specific report file.

1
2
3
4
5
6
7
8
# Define report ID (replace with actual report ID)
$reportId = "159b1276-8c12-4ac1-b58b-fb4dc656dd89"

# Send request to download report file
$reportFileResponse = Invoke-WebRequest -Uri "$requestUri/Reports/$reportId/file" -Method GET -Headers $headersToUseWithStagingReports -OutFile "staging-report-$reportId.csv"

# Display the response
Write-Host "Report file downloaded to staging-report-$reportId.csv"

Cancel Report

Send a DELETE request to cancel a specific report.

1
2
3
4
5
# Send request to cancel report
$cancelResponse = Invoke-RestMethod -Uri "$requestUri/Reports/$reportId" -Method DELETE -Headers $headersToUseWithStagingReports

# Display the response
$cancelResponse

Summary

• Replace <host> with your own host when using the samples.
• The access token is obtained via client credentials authentication.
• The Staging Reports API requires Bearer Token Authorization.
• The Staging Reports API uses v4 endpoints and supports comprehensive analysis of tenant data in staging containers.