Workspace Service API

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:

1
<host>/api/workspace-service/{version}/workspace/{workspaceId}/state

• Replace {version} with the API version you want to use. For example, v1.

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

RelativityOne REST API authentication

Overview

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

1. Cookie authentication
2. 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 also 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.

To generate a bearer token:

1. Create a Relativity OAuth2 Client using these instructions: OAuth2 clients on the RelativityOne Documentation site.
2. Generate a bearer token using these instructions: Bearer token authentication on the RelativityOne Documentation site.

3. Use the bearer token to make requests to Workspace Service API endpoints. For details on each endpoint, see API endpoints.

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

Get State

Permissions

To use the Get State endpoint, 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.

Calling the Get State endpoint

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

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

1
2
3
4
5
{
  "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.