Last date modified: 2026-Nov-12

Workspace Service API

The Workspace Manager API's UpdateAsync endpoint (PUT) is being deprecated December 9, 2026, as part of an effort to modernize and simplify the Relativity API surface. See this post in the developer group for more information.

This guide will help you get started with the Workspace Service API, including making your first requests, understanding the available endpoints, and authenticating your API calls.

Guidelines for the Workspace Service API

Review the following guidelines for working with this API.

URLs

The URLs for the REST API endpoints include a path parameter {version} that you need to set before making a call:

Copy
<host>/api/workspace-service/{version}/workspace/{workspaceId}/state
  • Replace {version} with the API version you want to use. For example, v1.
Copy
<host>/api/workspace-service/v1/workspace/{workspaceId}/state

Relativity aiR REST API authentication

Overview

To access the Workspace Service API, you must authenticate your requests. Relativity aiR supports two authentication methods:

  • Cookie authentication
  • Bearer token authentication

For more information on authentication methods, see Relativity REST API Authentication.

Cookie authentication

When a user logs into Relativity, the RelAuth cookie is issued to the browser. This encrypted cookie contains the information that validates the user. This cookie can be passed to REST service call instead of an HTTP authorization header. If the encrypted cookie is valid, the call will be authenticated under the credentials of the user who logged in via the web.

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:

  1. 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.
  2. 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>" \
  3. Use the Bearer Token by including the token in the Authorization header of your API requests.
  4. Copy
    curl -X GET "<host>/api/<servicename>/<versionnumber>/<endpoint>" \
         -H "Authorization: Bearer <your_access_token>"

Response codes

Workspace Service API uses conventional HTTP response codes to indicate the success or failure of an API request.

Generally:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed given the information provided. For example, a required parameter was omitted.
  • Codes in the 5xx range indicate an internal error with the Workspace Service API.

API endpoints

The following section describes the Workspace Service API endpoints.

To use the endpoints, you need to either have the View Workspace permission for the workspace whose state you want to check or be a System Administrator or a Relativity Services user.

Get State

To retrieve the state of a workspace, send a GET request with a URL in the following format:

Copy
<host>/api/workspace-service/v1/workspace/{workspaceId}/state
Copy
Sample JSON response:
{
  "WorkspaceId":1010100,
  "State":"Active",
  "SetOn":"2024-08-27T17:23:26.737"
}

Possible states of a workspace

The possible workspace states are:

  • None—the workspace exists, but has no assigned state.
  • Creating—the workspace is in the process of being created.
  • Active—the workspace is fully operational and available for use.
  • ColdStorage—the workspace is in Cold Storage. It cannot be accessed unless it is retrieved.
  • Errored—an error occurred. The workspace cannot be used.
  • RecycleBin—the workspace has been moved to the Recycle Bin and is pending permanent deletion or restoration. Workspaces stay in the Recycle Bin for seven days, and they can be retrieved during that time.
  • ScheduledForDeletion—the workspace is scheduled to be permanently deleted from the Recycle Bin. It cannot be retrieved.

Read Workspace

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

Copy
<host>/api/workspace-service/v1/workspace/{workspaceId}

If the workspace is upgrading, the endpoint returns 567 Workspace Temporarily Unavailable. You can retry after a short delay.

Copy
Sample JSON response:
{
  "ArtifactID": 1010100,
  "Name": "Sample Workspace",
  "Client": { "Value": { "ArtifactID": 2001, "Name": "Sample Client" }, "Secured": false },
  "Matter": { "Value": { "ArtifactID": 3001, "Name": "Sample Matter" }, "Secured": false },
  "ResourcePool": { "Value": { "ArtifactID": 4001, "Name": "Default" }, "Secured": false },
  "SqlServer": { "Value": { "ArtifactID": 5001, "Name": "SQL01" }, "Secured": false },
  "SqlFullTextLanguage": { "ID": 1033, "Name": "English" },
  "Status": { "ArtifactID": 6001, "Name": "Active" },
  "EnableDataGrid": false,
  "UseCase": "Litigation",
  "CreatedOn": "2024-08-27T17:23:26.737",
  "CreatedBy": { "ArtifactID": 9, "Name": "Admin, Relativity" },
  "LastModifiedOn": "2024-09-01T10:05:00.000",
  "LastModifiedBy": { "ArtifactID": 9, "Name": "Admin, Relativity" }
}         

Read Workspace with Metadata and Actions

To retrieve a workspace with optional metadata and actions, send a GET request with a URL in the following format:

Copy
<host>/api/workspace-service/v1/workspace/{workspaceId}/{includeMetadata}/{includeActions}           

The includeMetadata and includeActions values are required path segments, not query parameters. Each value is true or false. For example:

Copy
<host>/api/workspace-service/v1/workspace/1010100/true/true     

The options work as follows:

  • includeMetadata — when true, the response includes the Meta field, which lists unsupported and read-only properties on the workspace.

  • includeActions — when true, the response includes the Actions list, which shows the REST operations you can perform on the workspace.

Delete Workspace

To delete a workspace, send a DELETE request with a URL in the following format:

Copy
<host>/api/workspace-service/v1/workspace/{workspaceId}      

This request is a soft delete. The workspace moves to the Recycle Bin and no longer appears in normal views. A successful request returns 204 No Content with no response body.

Start Workspace Creation

To start workspace creation, send a POST request with a URL in the following format:

Copy
<host>/api/workspace-service/v1/workspace-job        
Copy
Sample JSON request:
{
  "Name": "Sample Workspace",
  "UseCase": "Litigation",
  "MatterArtifactId": 3001,
  "TemplateArtifactId": 7001,
  "StatusArtifactId": 6001,
  "SqlFullTextLanguage": 1033
}      

The request body can include the following fields:

Field Type Required Description
Name String Yes Workspace name. Must be 1–50 characters.
UseCase String Yes Use case for the workspace.
MatterArtifactId Integer No Artifact ID of the matter.
StatusArtifactId Integer No Artifact ID of the workspace status.
TemplateArtifactId Integer No Artifact ID of the template workspace.
SqlFullTextLanguage Integer No SQL full-text language ID.
Keywords String No Keywords for the workspace. Maximum 50 characters.
Notes String No Notes about the workspace.
DownloadHandlerUrl String No URL of the download handler.
WorkspaceAdminGroupArtifactId Integer No Artifact ID of the workspace admin group.
Copy
Sample JSON response:
{
  "JobId": "3f2b8c1e-5a4d-4e7a-9c1b-2d6f0a8e1b34"
}   

Get Workspace Creation Job Progress

To check job progress, send a GET request with a URL in the following format:

Copy
<host>/api/workspace-service/v1/workspace-job/{jobId}         

Copy
Sample JSON response:
{
  "JobId": "3f2b8c1e-5a4d-4e7a-9c1b-2d6f0a8e1b34",
  "WorkspaceArtifactId": 1010100,
  "TotalNumberOfSteps": 12,
  "CurrentStep": 12,
  "JobState": "Completed",
  "Attempt": 1
}          

Update Workspace

To update a workspace, send a PATCH request with a URL in the following format:

Copy
<host>/api/workspace-service/v1/workspace/{workspaceId}

This endpoint replaces the Workspace Manager API’s UpdateAsync (PUT) endpoint, which is being deprecated December 9, 2026.

Copy
Sample JSON request:
{
  "Name": "string",
  "MatterArtifactId": 1,
  "StatusArtifactId": 1,
  "ProductionRestrictionsArtifactId": 1,
  "SqlFullTextLanguage": 1,
  "Keywords": "string",
  "Notes": "string",
  "UseCase": "string",
  "WorkspaceAdminGroupArtifactId": 1
}

The request body can include the following fields:

Field Type Required Description
Name String Yes Workspace name. Must be 1–50 characters.
UseCase String Yes Use case for the workspace.
MatterArtifactId Integer No Artifact ID of the matter.
StatusArtifactId Integer No Artifact ID of the workspace status.
SqlFullTextLanguage Integer No SQL full-text language ID.
Keywords String No Keywords for the workspace. Maximum 50 characters.
ProductionRestrictionsArtifactId Integer Yes Artifact ID of the Production Restrictions saved search. Send null to clear.
Notes String No Notes about the workspace.
WorkspaceAdminGroupArtifactId Integer No Artifact ID of the workspace admin group.

A successful request returns 204 No Content with no response body.

Feedback