Review Center (REST)

The Review Center API provides REST access to Review Center data in your Relativity workspace, starting with queue statistics. These are the same queue-level figures shown on the Review Center dashboard - totals, remaining items, coded counts, and, for validation queues, quality metrics such as elusion, precision, richness, and recall.

Typical use cases:

Feeding review progress into an external reporting dashboard or business intelligence tool.
Monitoring coding throughput across one or more queues on a schedule.
Capturing point-in-time statistics as part of a project milestone workflow.

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

Methods

The Review Center API currently consists of 1 endpoint:

statistics/current - return the current statistics for a Review Center queue. The response shape depends on the queue type; the queue_type_choice_guid field identifies it and names the schema that applies.

Request and response details for each endpoint are in the Review Center REST API Reference.

Base URL

All requests use your Relativity instance's URL as the base URL:

Copy

1
https://{your-instance}.relativity.one/review-center-multi-tenant-service

Authentication

The Review Center API uses a bearer token to authenticate requests.

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.

When multiple web servers are hosted behind a load balanced route, you can't programmatically retrieve an authentication token. You must use a direct route to one of the web servers to retrieve the authentication token.

To create, obtain and use a bearer access token:

Create a Relativity OAuth2 Client (for more information see OAuth2 clients on the Relativity aiR Documentation site):
- Click Home > Authentication > OAuth2 Client Manager.
- Click New OAuth2 Client to create a new client, or click Edit to modify an existing client.
- Complete the fields on the form. Fields in orange are required:
  - Name- enter a unique name for the OAuth2 client.
  - Enabled- indicate whether the client will have access to Relativity.
  - Flow Grant Type- select Client Credentials.
  - Context User- select a user with the appropriate level of permissions or group membership for the operations you want to perform. (Usually a member of the Relativity Administrators group, but could be different depending on the API or operation invoked).
  - Access Token Lifetime- set the duration (in minutes) for which access tokens are valid. The recommended value is 60 minutes.
- Click Save to create the OAuth2 client. For more information, see OAuth2 clients on the Relativity aiR Documentation site.

Obtain a Bearer Token by sending 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>" \

Use the Bearer Token by including the token in the Authorization header of your API requests.

Copy

curl -X GET "<host>/api/<servicename>/<versionnumber>/<endpoint>" \
     -H "Authorization: Bearer <your_access_token>"

Permissions

Statistics are computed in the security context of the OAuth2 client's context user. That user must have:

Access to the workspace identified by {workspaceID}.
View permission on the Review Center Queue object, including the specific queue identified by {queueID}.

Finding workspace and queue IDs

Workspace ID - the workspace's Artifact ID. It appears in the browser URL while you are in the workspace, as the AppID query parameter.
Queue ID - the Artifact ID of the Review Center queue. Query the Review Center Queue object type with the Object Manager (REST) service, using the same bearer token. A queryslim request returns each queue's ArtifactID and name:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
POST /Relativity.Rest/api/Relativity.ObjectManager/v1/workspace/{workspaceID}/object/queryslim
Authorization: Bearer eyJhbGciOi...
X-CSRF-Header: -
Content-Type: application/json

{
  "Request": {
    "ObjectType": { "Name": "Review Center Queue" },
    "fields": [ { "Name": "Name" } ],
    "condition": ""
  },
  "start": 1,
  "length": 100
}

Response (200 OK, trimmed):

Copy

1
2
3
4
5
6
7
8
{
  "TotalCount": 3,
  "Objects": [
    { "ArtifactID": 1539420, "Values": [ "4. Prioritized Review" ] },
    { "ArtifactID": 1539428, "Values": [ "2. 2nd Level Review-Privilege Term QC" ] },
    { "ArtifactID": 1539432, "Values": [ "1. 1st Level Review-Threaded" ] }
  ]
}

Errors

The API uses conventional HTTP response codes to indicate the success or failure of a request:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate a problem with the request, such as an invalid token or insufficient permissions.
Codes in the 5xx range indicate an internal error.

Response codes

200 - OK: statistics were computed and returned in the response body
204 - No Content: the request succeeded but no statistics are available for the queue
401 - Unauthorized: no valid bearer token was provided
403 - Forbidden: the context user does not have permission to view the queue. A queue that does not exist, or is not visible to that user, returns the same response.
404 - Not Found: no endpoint matches the request URL
5xx - Server Errors: something went wrong on the Review Center API end

Client code generation

The API is described by an OpenAPI (OAS 3) document. Download it from the Integration APIs and Services page - use the REST OAS file link in this API's row, or the bundled OASFiles.zip linked at the top of the page. You can use the document with any OAS-compatible generator, such as NSwagStudio, to produce a typed client. See Get started with NSwag and ASP.NET Core on the Microsoft website for an example workflow.

Code samples

Calling the API with PowerShell

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$token = "<your-bearer-token>"
$workspaceId = 1234567
$queueId = 2345678
$baseUrl = "https://your-instance.relativity.one"

$response = Invoke-RestMethod `
    -Method Get `
    -Uri "$baseUrl/review-center-multi-tenant-service/api/external/v1/workspaces/$workspaceId/reviews/queues/$queueId/statistics/current" `
    -Headers @{ Authorization = "Bearer $token" }

if (-not $response) {  # a 204 response carries no body, so Invoke-RestMethod returns nothing
    Write-Host "No statistics are available for this queue yet."
    return
}

Write-Host "Total: $($response.total_items_count), remaining: $($response.total_items_remaining_count)"

Calling the API with C# and HttpClient

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var httpClient = new HttpClient();
var token = "<your-bearer-token>";
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var workspaceId = 1234567;
var queueId = 2345678;
var url = $"https://your-instance.relativity.one/review-center-multi-tenant-service/api/external/v1/workspaces/{workspaceId}/reviews/queues/{queueId}/statistics/current";

using var response = await httpClient.GetAsync(url);
response.EnsureSuccessStatusCode();

// A 204 response carries no body; deserializing it would throw.
if (response.StatusCode == HttpStatusCode.NoContent)
{
    Console.WriteLine("No statistics are available for this queue yet.");
    return;
}

var stats = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();
Console.WriteLine($"Total items: {stats?["total_items_count"]}, remaining: {stats?["total_items_remaining_count"]}");