Staging Reports API (REST)

The Staging Reports API provides a REST service that allows you to generate folder and file reports about tenant data.

With this API you can:

• Enumerate folders.
• Generate folder or file reports.
• Retrieve lists of submitted reports.
• Retrieve generated reports as a file.

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

Resources

• Staging Reports API Reference

Guidelines for the Staging Reports API

Review the following guidelines for working with this API.

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.

Permissions

To use the Staging Reports API you need the View Staging Report instance permission and be either a System Administrator or a Client Domain Administrator. For more information, see Setting instance permissions.

URLs

The URLs for REST endpoints are fixed to use version v3 of the REST API.

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

For example, you can use the following URL to retrieve containers:

1
<host>/Relativity.Rest/API/staging-insights/v3/directory/containers

Set a HTTP request header field X-Kepler-Referrer to your URL, if the header is missing you will get a http 400 BadRequest response

1
"X-Kepler-Referrer": <applicationGUID>

Set an HTTP request header field X-Csrf-Header to -. If the header is missing you will get a HTTP 404 NotFound response.

1
"X-Csrf-Header": -

Postman sample file

You can use the Postman sample file to become familiar with making calls to endpoints on the Notifications Manager service. To download the sample file, click Staging Reports 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.

Get containers

To retrieve containers, send a GET request with a URL in the following general format:

1
<host>/Relativity.Rest/API/staging-insights/v3/directory/containers

1
2
3
4
5
6
7
8
9
10
{
    "Containers": [
        {
            "ContainerName": "t021"
        },
        {
            "ContainerName": "t021a"
        }
    ]
}

Get directories

To retrieve directories, send a POST request with a URL in the following general format:

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

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

The JSON key path must follow Unix format (using / as a separator) and begin with the container name, without slashes.

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/Folder-300"
    ],
    "Paging": {
        "Start": 1,
        "Limit": 300
    }
}

Create report

To create a report, send a POST request with a URL in the following general format:

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

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

The JSON key path must follow Unix format (using / as a separator) and begin with the container name, without slashes.

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

Cancel report

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

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

1
true

Get reports

To list all reports, send a POST request with a URL in the following general format:

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

1
2
3
4
5
6
7
8
{
    "jobsRequest": {
        "paging": {
            "start": 1,
            "limit": 200
        }
    }
}

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
27
{
    "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 a URL in the following general format:

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

Get billable summary report

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 a URL in the following general format:

1
<host>/Relativity.Rest/API/staging-insights/v3/billable-summary-reports?container={{container}}&date={{date}}

Date should be in YYYYMMDD format.

Get billable summary report list

To retrieve a list of billable summary reports, send a POST request with a URL in the following general format:

<host>/Relativity.Rest/API/staging-insights/v3/billable-summary-reports/list

1
2
3
4
5
6
7
8
{
  "billableSummaryListRequest": {
    "paging": {
      "start": 1,
      "limit": 200
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "Reports": [
        {
            "Container": "t021",
            "Date": "2023-11-17T14:21:35.2681337Z"
        },
        ....
        {
            "Container": "t021a",
            "Date": "2023-11-17T14:20:47.9840466Z"
        }
    ],
    "TotalCount": 2
}

Using the Staging Reports API from a PowerShell script

To retrieve a report using PowerShell use the following script:

$uri = '/relativity.rest/api/staging-insights/v3/billable-summary-reports?container=t030&date=20241021'

$headers = @{
    Authorization = 'Bearer abc123'
    "X-Kepler-Referrer" = "<applicationGuid>"
    "X-Csrf-Header"     = "-"
}

$response = Invoke-WebRequest -Uri $uri -Headers $headers -Method GET
$responseUtf8 = [System.Text.Encoding]::UTF8.GetString($response.Content)

Write-Output 'Report content:'
$responseUtf8 | ConvertFrom-CSV

The above script uses the Invoke-WebRequest method to retrieve the full response; content, headers, and cookies. It gives you more possibilities when converting the web response content to other objects (e.g. text). One of the possibility is using specific encoding (e.g. UTF8).

The PowerShell method Invoke-RestMethod automatically converts the response to PowerShell objects but has limited possibilities in changing the encoding while converting the response into text.