Workspace Manager (REST)

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 post in the developer group.
Several Workspace Manager API endpoints have already been deprecated as part of an effort to modernize and simplify the Relativity API surface. See this post in the developer group for more information.

In Relativity, a workspace acts as a secure data repository for documents. It supports customized views, layouts, fields, choices, and security settings. For more information, see Workspaces on the RelativityOne Documentation site.

The Workspace Manager service supports the following functionality:

CRUD operations on workspaces.
Helper endpoints for retrieving lists of available resources, such as matters, clients, and others.
Helper endpoints for retrieving information about advanced settings, such as workspace statuses, full text languages for the SQL Server, and others.

As a sample use case, you can simplify setting up reviews by using the Workspace Manager service to programmatically create multiple workspaces rather than manually adding them through the Relativity UI.

You can also use the Workspace Manager service through the .NET. For more information, see Workspace Manager (.NET).

Guidelines for the Workspace Manager service

Review the following guidelines for working with this service.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:
- Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1.
- Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.
Ensure that the X-CSRF-Header is set.
If applicable, for more information on the retrieving the Artifact ID, see Relativity artifact identifiers.

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

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/{workspaceID}

Set the path parameters as follows:

{versionNumber} to the version of the API, such as v1.
{workspaceID} to the Artifact ID of a specific workspace.

Client code sample

To use the Workspace Manager service, send requests by making calls with the required HTTP methods. Use the following base URL for this service:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/

The following sample code is simple .NET client that illustrates how to use the Workspace Manager service to make REST calls.

View code sample

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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
private HttpClient GetHttpClient()
{
    HttpClient httpClient = new HttpClient();
 
    httpClient.BaseAddress = new Uri("https://localhost/");
    httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
    httpClient.DefaultRequestHeaders.Add("Authorization", "Basic " +
        Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test@test.com:SomePassword")));
 
    return httpClient;
}
 
private string BASE_URL = "Relativity.Rest/API/relativity-environment/v1/workspace";
 
private async Task<List<int>> GetArtifactIDList(HttpClient httpClient, string url)
{
    HttpResponseMessage response = await httpClient.GetAsync(url);
    string resultString = await response.Content.ReadAsStringAsync();
 
    var artifactIDs = new List<int>();
     
    dynamic objects = JArray.Parse(resultString) as JArray;
    foreach (var obj in objects)
    {
        int artifactID = obj.ArtifactID;
        artifactIDs.Add(artifactID);
    }
 
    return artifactIDs;
}
 
private async Task<List<int>> QueryArtifactIDList(HttpClient httpClient, string url)
{
    var queryRequest = new
    {
        request = new
        {
            Fields = new[]
            {
                new { Name = "*" }
            },
            Condition = ""
        },
        start = 1,
        length = 1000
    };
 
    StringContent payload = new StringContent(JsonConvert.SerializeObject(queryRequest), Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(url, payload);
    string resultString = await response.Content.ReadAsStringAsync();
 
    var artifactIDs = new List<int>();
 
    dynamic result = JObject.Parse(resultString) as JObject;
    foreach (var obj in result.Objects)
    {
        int artifactID = obj.ArtifactID;
        artifactIDs.Add(artifactID);
    }
 
    return artifactIDs;
}
 
public async Task<List<int>> GetEligibleStatuses(HttpClient httpClient)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-statuses");
}
 
public async Task<List<int>> GetEligibleResourcePools(HttpClient httpClient)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-resource-pools");
}
 
public async Task<List<int>> GetEligibleFileRepositories(HttpClient httpClient, int resourcePoolID)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-resource-pools/{resourcePoolID}/eligible-file-repositories");
}
 
public async Task<List<int>> GetEligibleCacheLocations(HttpClient httpClient, int resourcePoolID)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-resource-pools/{resourcePoolID}/eligible-cache-locations");
}
 
public async Task<List<int>> GetEligibleSqlServers(HttpClient httpClient, int resourcePoolID)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-resource-pools/{resourcePoolID}/eligible-sql-servers");
}
 
public async Task<List<int>> GetEligibleAzureCredentials(HttpClient httpClient, int resourcePoolID)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-resource-pools/{resourcePoolID}/eligible-azure-credentials");
}
 
public async Task<List<int>> GetEligibleAzureFileSystemCredentials(HttpClient httpClient, int resourcePoolID)
{
    return await GetArtifactIDList(httpClient, $"{BASE_URL}/eligible-resource-pools/{resourcePoolID}/eligible-azure-file-system-credentials");
}
 
public async Task<List<int>> QueryEligibleMatters(HttpClient httpClient)
{
    return await QueryArtifactIDList(httpClient, $"{BASE_URL}/query-eligible-matters");
}
 
public async Task<List<int>> QueryEligibleTemplates(HttpClient httpClient)
{
    return await QueryArtifactIDList(httpClient, $"{BASE_URL}/query-eligible-templates");
}
 
public async Task<int> GetDefaultSqlFullTextLanguage(HttpClient httpClient)
{
    HttpResponseMessage response = await httpClient.GetAsync($"{BASE_URL}/eligible-sql-full-text-languages");
    string resultString = await response.Content.ReadAsStringAsync();
    dynamic languages = JObject.Parse(resultString) as JObject;
    int defaultLanguageID = languages.DefaultLanguageLcid;
    return defaultLanguageID;
}
 
public async Task<string> GetDefaultDownloadHandlerUrl(HttpClient httpClient)
{
    HttpResponseMessage response = await httpClient.GetAsync($"{BASE_URL}/default-download-handler-url");
    string result = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<string>(result);
}
 
public async Task<int> CreateWorkspace(string name)
{
    HttpClient httpClient = GetHttpClient();
 
    int statusID = (await GetEligibleStatuses(httpClient)).First();
    int matterID = (await QueryEligibleMatters(httpClient)).First();
    string defaultDownloadHandlerUrl = await GetDefaultDownloadHandlerUrl(httpClient);
    int resourcePoolID = (await GetEligibleResourcePools(httpClient)).First();
    int fileRepositoryID = (await GetEligibleFileRepositories(httpClient, resourcePoolID)).First();
    int cacheLocationID = (await GetEligibleCacheLocations(httpClient, resourcePoolID)).First();
    int sqlServerID = (await GetEligibleSqlServers(httpClient, resourcePoolID)).First();
    int sqlFullTextLanguage = await GetDefautlSqlFullTextLanguage(httpClient);
    int templateID = (await QueryEligibleTemplates(httpClient)).First();
 
    var payloadObject = new
    {
        workspaceRequest = new
        {
            Name = name,
            Status = new { ArtifactID = statusID },
            Matter = new { Secured = false, Value = new { ArtifactID = matterID } },
            DownloadHandlerUrl = defaultDownloadHandlerUrl,
            ResourcePool = new { Secured = false, Value = new { ArtifactID = resourcePoolID } },
            DefaultFileRepository = new { Secured = false, Value = new { ArtifactID = fileRepositoryID } },
            DefaultCacheLocation = new { Secured = false, Value = new { ArtifactID = cacheLocationID } },
            SqlServer = new { Secured = false, Value = new { ArtifactID = sqlServerID } },
            SqlFullTextLanguage = sqlFullTextLanguage,
            Template = new { Secured = false, Value = new { ArtifactID = templateID } },
            Keywords = "sample keywords for workspace",
            Notes = "sample notes for workspace"
        }
    };
 
    StringContent payload = new StringContent(JsonConvert.SerializeObject(payloadObject), Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync($"{BASE_URL}/", payload);
    string resultString = await response.Content.ReadAsStringAsync();
 
    dynamic result = JObject.Parse(resultString) as JObject;
    int artifactID = result.ArtifactID;
    return artifactID;
}

Create operation helper methods

The following helper endpoints provide functionality to support the create operation.

Retrieve unsupported fields for a create operation

To retrieve unsupported fields on a WorkspaceRequest object for a create operation, send a GET request with a URL in the following general format:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/meta

The request body is empty.

The response contains the following fields

Unsupported - an array of fields that aren't supported on the WorkspaceRequest object for a create operation.
ReadOnly - an array of fields that can't be modified on the WorkspaceRequest object for a create operation.

Copy

1
2
3
4
5
6
7
{
    "Unsupported": [
        "AzureCredentials",
        "AzureFileSystemCredentials"
    ],
    "ReadOnly": []
}

Retrieve a workspace

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

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/{workspaceID}

The response for a read operation contains many of the same fields as those for a body of a create request. See Workspace Manager (REST).

View sample JSON response

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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{
  "ArtifactID": 245678,
  "Guids": [
    "CE780D86-4217-45D7-83A2-0934F2F66B17"
  ],
  "Name": "New Workspace",
  "Matter": {
    "Secured": false,
    "Value": {
      "ArtifactID": 123456
    }
  },
  "Status": {
    "ArtifactID": 345678
  },
  "ResourcePool": {
    "Secured": false,
    "Value": {
      "ArtifactID": 456789
    }
  },
  "SqlServer": {
    "Secured": false,
    "Value": {
      "ArtifactID": 567890
    }
  },
  "DefaultFileRepository": {
    "Secured": false,
    "Value": {
      "ArtifactID": 567890
    }
  },
  "DefaultCacheLocation": {
    "Secured": false,
    "Value": {
      "ArtifactID": 567890
    }
  },
  "DownloadHandlerUrl": "Relativity.Distributed",
  "EnableDataGrid": false,
  "ProductionRestrictions": {
    "Secured": false,
    "Value": {
      "ArtifactID": 678901
    }
  },
  "DataGridFileRepository": {
    "Secured": false,
    "Value": {
      "ArtifactID": 789012
    }
  },
  "AzureCredentials": {
    "Secured": false,
    "Value": {
      "ArtifactID": 890123
    }
  },
  "AzureFileSystemCredentials": {
    "Secured": false,
    "Value": {
      "ArtifactID": 901234
    }
  },
  "SqlFullTextLanguage": "English",
  "WorkspaceAdminGroup": {
    "Secured": false,
    "Value": {
      "ArtifactID": 134567
    }
  },
  "Keywords": "",
  "Notes": ""
}

Update a workspace

To modify the properties of a workspace, send a PUT request with a URL in the following general format:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/{workspaceID}

View field descriptions for an update request

For read-only fields, set their Secured property set to true, and set their Value properties to null. For more information, see Field permissions.

The body of request must contain a workspaceRequest object with the following fields:

Name - the user-friendly name of the workspace.
Matter - represents a securable matter object. A matter is the case or legal action associated with the workspace. It contains the following fields:
- Secured - a Boolean value indicating whether the current user has permissions to view the settings in the Value field. The user can't view the Value field when this value is true. For a create request, set this value to false.
- Value - contains the following fields:
  - ArtifactID - an integer used as a unique identifier for the object.
  - Guids - an array of GUIDs used to identify the object.
Template - an object representing an existing workspace structure used to create the workspace. See descriptions for the Secured and Value fields under Matter.

Leave the Template property blank because you can only set it at workspace creation.

Status - represents a workspace status object associated with the workspace. It contains the following field:
- ArtifactID - an integer used to identify the status.
ResourcePool - represents a securable resource pool object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
SqlServer - represents a securable SQL server object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
DefaultFileRepository - represents a securable file repository server object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
DefaultCacheLocation - represents a securable cache location server object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
DownloadHandlerUrl - a string representing the default URL used to make downloaded files available to users.
EnableDataGrid - a Boolean value indicating whether the workspace can have fields that save to Data Grid. This field can't be set during update operation - the value will always be set to True.
ProductionRestrictions - represents a securable saved search object used for production restrictions. See descriptions for the Secured and Value fields under Matter.
DataGridFileRepository - represents a securable file repository server object used for Data Grid. See descriptions for the Secured and Value fields under Matter.
AzureCredentials - represents a securable Azure credentials object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
AzureFileSystemCredentials - represents a securable Azure file system credentials object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
SqlFullTextLanguage - an integer representing the ID of the language used for determining the word-break characters used in the full text index for the workspace.
WorkspaceAdminGroup - a securable group object associated with the workspace. See descriptions for the Secured and Value fields under Matter.
Keywords - optional words or phrases used to describe the workspace.
Notes - additional information about the workspace.

View sample JSON request

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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
{
  "workspaceRequest": {
    "Name": "New Workspace",
    "Matter": {
      "Secured": false,
      "Value": {
        "ArtifactID": 123456
      }
    },
    "Template": {
      "Secured": false,
      "Value": {
        "ArtifactID": 234567
      }
    },
    "Status": {
      "ArtifactID": 345678
    },
    "ResourcePool": {
      "Secured": false,
      "Value": {
        "ArtifactID": 456789
      }
    },
    "SqlServer": {
      "Secured": false,
      "Value": {
        "ArtifactID": 567890
      }
    },
    "DefaultFileRepository": {
      "Secured": false,
      "Value": {
        "ArtifactID": 567890
      }
    },
    "DefaultCacheLocation": {
      "Secured": false,
      "Value": {
        "ArtifactID": 567890
      }
    },
    "DownloadHandlerUrl": "Relativity.Distributed",
    "EnableDataGrid": false,
    "ProductionRestrictions": {
      "Secured": false,
      "Value": {
        "ArtifactID": 678901
      }
    },
    "DataGridFileRepository": {
      "Secured": false,
      "Value": {
        "ArtifactID": 789012
      }
    },
    "AzureCredentials": {
      "Secured": false,
      "Value": {
        "ArtifactID": 890123
      }
    },
    "AzureFileSystemCredentials": {
      "Secured": false,
      "Value": {
        "ArtifactID": 901234
      }
    },
    "SqlFullTextLanguage": 1033,
    "WorkspaceAdminGroup": {
      "Secured": false,
      "Value": {
        "ArtifactID": 134567
      }
    },
    "Keywords": "",
    "Notes": ""
  }
}

The response for an update operation contains the same fields as those for a request. See the field descriptions for View field descriptions for an update request.

View sample JSON response

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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "ArtifactID": 245678,
  "Guids": [
    "CE780D86-4217-45D7-83A2-0934F2F66B17"
  ],
  "Name": "New Workspace",
  "Matter": {
    "Secured": false,
    "Value": {
      "ArtifactID": 123456
    }
  },
  "Template": {
    "Secured": false,
    "Value": {
      "ArtifactID": 234567
    }
  },
  "Status": {
    "ArtifactID": 345678
  },
  "ResourcePool": {
    "Secured": false,
    "Value": {
      "ArtifactID": 456789
    }
  },
  "SqlServer": {
    "Secured": false,
    "Value": {
      "ArtifactID": 567890
    }
  },
  "DefaultFileRepository": {
    "Secured": false,
    "Value": {
      "ArtifactID": 567890
    }
  },
  "DefaultCacheLocation": {
    "Secured": false,
    "Value": {
      "ArtifactID": 567890
    }
  },
  "DownloadHandlerUrl": "Relativity.Distributed",
  "EnableDataGrid": false,
  "ProductionRestrictions": {
    "Secured": false,
    "Value": {
      "ArtifactID": 678901
    }
  },
  "DataGridFileRepository": {
    "Secured": false,
    "Value": {
      "ArtifactID": 789012
    }
  },
  "AzureCredentials": {
    "Secured": false,
    "Value": {
      "ArtifactID": 890123
    }
  },
  "AzureFileSystemCredentials": {
    "Secured": false,
    "Value": {
      "ArtifactID": 901234
    }
  },
  "SqlFullTextLanguage": 1033,
  "WorkspaceAdminGroup": {
    "Secured": false,
    "Value": {
      "ArtifactID": 134567
    }
  },
  "Keywords": "",
  "Notes": ""
}

Retrieve workspace statistics

To retrieve a summary of workspace statistics, send a GET request to a URL in the following general format:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/{workspaceID}/summary

The request body is empty.

The response contains the following fields:

DocumentCount - a long representing the number of documents in a workspace.
FileSize - a long representing the total size of the workspace files in bytes.

Copy

1
2
3
4
{
  "DocumentCount": 73973,
  "FileSize": 0
}

Advanced settings helper methods

The following helper methods correspond to the fields that you can set in the Advanced settings section of the Workspace form in the Relativity UI. For more information, see Workspaces on the RelativityOne Documentation site.

Retrieve available statuses for a workspace

To retrieve available statuses for a workspace, send a GET request with a URL in the following general format:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/eligible-statuses

The request body is empty.

View a sample Json response

Copy

1
2
3
4
5
6
7
[
    {
        "Name": "Active",
        "ArtifactID": 675,
        "Guids": []
    }
]

Retrieve full text languages for SQL Server

To retrieve a list of available full text languages for the SQL Server assigned to a workspace, send a GET request to a URL in the following general format:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/eligible-sql-full-text-languages

View a sample Json response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "DefaultLanguageLcid": 1033,
  "Languages": [
    {
      "Name": "Arabic",
      "ID": 1025
    },
    {
      "Name": "Bengali (India)",
      "ID": 1093
    },
    {
      "Name": "Bokmål",
      "ID": 1044
    },
    {
      "Name": "Vietnamese",
      "ID": 1066
    }
  ]
}

Retrieve saved searches for production restrictions

You can retrieve saved searches for use with production restrictions. For more information, see Adding and editing production restrictions on the RelativityOne Documentation site.

Send a POST request with a URL in the following general format:

Copy

1
<host>/Relativity.Rest/API/relativity-environment/{versionNumber}/workspace/{workspaceID}/query-eligible-saved-searches

This endpoint uses the same format for requests and responses as the query for matters. For field descriptions and sample JSON, see Workspace Manager (REST).