Application Install service
Through the REST API, the Application Install API allows clients to install applications into one or more workspaces, cancel pending installations, as well as get the status of any specified application installations. Additionally, this API allows support for conflict resolution for any failed application installations.
This page contains the following information:
- Client code sample
- Field descriptions for JSON requests
- InstallApplicationAsync
- InstallApplicationAllAsync
- GetStatusAsync
- GetOutdatedWorkspacesCount
- CancelAsync
- GetApplicationInstallDetailsAsync
- GetApplicationInstallDetailsReportAsync
- CancelAllAsync
- SearchAsync
- SearchApplicationAsync
- IsNameAvailable
- GetAvailableWorkspacesAsync
Client code sample
To use the Application Install service, send requests by making calls with the required HTTP methods. See the following base URL for this service:
<host>/Relativity.REST/API/Relativity.LibraryApplications/workspace/-1/libraryapplications/ |
Note: For the workspace identifier in the URL, use -1 to indicate the admin-level context. This value is required for all URLs in the Application Install service. For additional guidelines, see Application Install API.
Field descriptions for JSON requests
The Application Install service uses many common fields for JSON requests.
InstallApplicationAsync
To install an application to one or more workspaces, send a POST request with one of the following URLs:
1 2 3 4 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{IncludeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{IncludeActions} |
InstallApplicationAllAsync
To install an application to one or more workspaces, send a POST request with one of the following URLs:
1 2 3 4 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/installall https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/installall/{IncludeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/installall https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/installall/{IncludeActions} |
The client can specify one of two options for Mode:
- ForceInstall
- UpgradeOnly
GetStatusAsync
To get the installation status of an application, send a GET request with one of the following URLs. The request URL can take either the application's ArtifactID or the Guid.
1 2 3 4 5 6 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/{IncludeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/{IncludeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/{workspaceID}/libraryapplications/{artifactID}/install?{IncludeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/{workspaceID}/libraryapplications/{applicationGuid}/install?{IncludeActions} |
The body of the request is empty.
If the installation failed due to validation errors (duplicate name or locked app conflicts), the endpoint is invoked with the includeActions flag, then the JSON response will have the conflicts listed and with a sample request to retry the installation.
GetOutdatedWorkspacesCount
To retrieve the number of outdated workspace installations associated with an application, send a GET request with the following URLs:
1 2 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/outdated-workspaces-count https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactGuid}/install/outdated-workspaces-count |
The body of the request should be empty.
If the count of outdated workspace installations is greater than zero, the response will include an action to update all outdated applications to the latest version available in the Application Library, as well as the payload associated with the action. The JSON response would look like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "ApplicationIdentifier" : { "ArtifactID" : 1017669, "Guids" : [ "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b" ] }, "IsGlobalApplication" : false , "OutdatedWorkspacesCount" : 2, "UpdateOutdatedApplications" : { "Name" : "UpdateOutdatedApplications" , "Href" : "Relativity.LibraryApplications/workspace/-1/libraryapplications/1017669/install/all" , "Verb" : "GET" , "IsAvailable" : true , "Reason" : [] }, "UpdateOutdatedApplicationsPayload" : { "Mode" : "UpgradeOnly" , "UnlockApplications" : true } } |
CancelAsync
To cancel one or more application installations, send a DELETE request with one of the following URLs:
1 2 3 4 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install |
If the endpoint is invoked with a single application installation ID, the JSON request should be empty.


GetApplicationInstallDetailsAsync
This endpoint retrieves the installation details for a specified application and application installation ID, send a GET request with one of the following URLs:
1 2 3 4 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/details/{start}/{length} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/details/{start}/{length} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/details/{start}/{length}/{includeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/details/{start}/{length}/{includeActions} |
The body of the request is empty.

GetApplicationInstallDetailsReportAsync
This endpoint has two different implementations. To get a report, send a GET request with one of the following URLs:
1 2 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/details/csv https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/details/csv |
The response will be an IKeplerStream object. In a browser context, this will be turned into a file download.
CancelAllAsync
This endpoint cancels all pending application installs associated with a specified application. To cancel all pending application installations, send a DELETE request with one of the following URLs:
1 2 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/all https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/all |
The JSON request should be empty.
SearchAsync
This endpoint has one implementation with optional query fields start (default: 1), length (default: 10), and includeActions (default: false). To search application installations, send a POST request the following URL:
https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/install/search?start={start}&length={length}&includeActions={includeActions} |
Note: The includeActions parameter controls whether the pagination properties are populated. If your workflow requires iterating through pages of results using these properties, you need to include the includeActions parameter in your method call with the value set true on in the request. For more information, see Actions and pagination.
JSON Response
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 166 167 168 | { "Results" : [ { "ApplicationInstallID" : 53769, "ApplicationIdentifier" : { "Name" : "Imaging" , "ArtifactID" : 1015285, "Guids" : [ "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b" ] }, "WorkspaceIdentifier" : { "Name" : "Admin Case" , "ArtifactID" : -1, "Guids" : [] }, "RootFolderID" : 0, "InstallStatus" : { "Code" : "Completed" , "GetDetailsAction" : { "Name" : "GetInstallDetails-DefaultPage" , "Href" : "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/53769/details/1/10" , "Verb" : "GET" , "IsAvailable" : true , "Reason" : [] } }, "Version" : "11.1.0.0" , "IsOutOfDate" : false , "InstalledBy" : { "Name" : "Service Account, Relativity" , "ArtifactID" : 777, "Guids" : [] }, "StartedOn" : "2019-12-02T17:01:32.753" , "CompletedOn" : "2019-12-02T17:01:49.923" }, { "ApplicationInstallID" : 53784, "ApplicationIdentifier" : { "Name" : "Imaging" , "ArtifactID" : 1015285, "Guids" : [ "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b" ] }, "WorkspaceIdentifier" : { "Name" : "New Case Template" , "ArtifactID" : 1014823, "Guids" : [] }, "ClientIdentifier" : { "Name" : "Relativity Template" , "ArtifactID" : 1006066, "Guids" : [] }, "MatterIdentifier" : { "Name" : "Relativity Template" , "ArtifactID" : 1000002, "Guids" : [] }, "RootFolderID" : 1003697, "InstallStatus" : { "Code" : "Completed" , "GetDetailsAction" : { "Name" : "GetInstallDetails-DefaultPage" , "Href" : "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/53784/details/1/10" , "Verb" : "GET" , "IsAvailable" : true , "Reason" : [] } }, "Version" : "11.1.0.0" , "IsOutOfDate" : false , "InstalledBy" : { "Name" : "Service Account, Relativity" , "ArtifactID" : 777, "Guids" : [] }, "StartedOn" : "2019-12-02T17:02:12.11" , "CompletedOn" : "2019-12-02T17:02:55.58" }, { "ApplicationInstallID" : 53801, "ApplicationIdentifier" : { "Name" : "Imaging" , "ArtifactID" : 1015285, "Guids" : [ "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b" ] }, "WorkspaceIdentifier" : { "Name" : "Relativity Starter Template" , "ArtifactID" : 1015024, "Guids" : [] }, "ClientIdentifier" : { "Name" : "Relativity Template" , "ArtifactID" : 1006066, "Guids" : [] }, "MatterIdentifier" : { "Name" : "Relativity Template" , "ArtifactID" : 1000002, "Guids" : [] }, "RootFolderID" : 1003697, "InstallStatus" : { "Code" : "Completed" , "GetDetailsAction" : { "Name" : "GetInstallDetails-DefaultPage" , "Href" : "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/53801/details/1/10" , "Verb" : "GET" , "IsAvailable" : true , "Reason" : [] } }, "Version" : "11.1.0.0" , "IsOutOfDate" : false , "InstalledBy" : { "Name" : "Service Account, Relativity" , "ArtifactID" : 777, "Guids" : [] }, "StartedOn" : "2019-12-02T17:02:17.017" , "CompletedOn" : "2019-12-02T17:03:00.283" } ], "Summary" : { "Other" : 0, "Pending" : 0, "InProgress" : 0, "Failed" : 0, "Completed" : 37, "Canceled" : 0, "TotalActiveInstalls" : 0, "Total" : 37 }, "CurrentStartIndex" : 1, "ResultCount" : 3, "TotalCount" : 37, "FirstPage" : { "Name" : "SearchStatus-FirstPage" , "Verb" : "POST" , "IsAvailable" : false , "Reason" : [] }, "PreviousPage" : { "Name" : "SearchStatus-PreviousPage" , "Verb" : "POST" , "IsAvailable" : false , "Reason" : [] }, "NextPage" : { "Name" : "SearchStatus-NextPage" , "Href" : "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/search?start=4&length=3&includeActions=true" , "Verb" : "POST" , "IsAvailable" : true , "Reason" : [] }, "LastPage" : { "Name" : "SearchStatus-LastPage" , "Href" : "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/search?start=37&length=3&includeActions=true" , "Verb" : "POST" , "IsAvailable" : true , "Reason" : [] } } |
SearchApplicationAsync
This endpoint has two implementations with optional query fields start (default: 1), length (default: 10), and includeActions (default: false). To search application installations, send a POST request to one of the following URLs:
1 2 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationID:int}/install/search?start={start}&length={length}&includeActions={includeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid:guid}/install/search?start={start}&length={length}&includeActions={includeActions} |
Note: The includeActions parameter controls whether the pagination properties are populated. If your workflow requires iterating through pages of results using these properties, you need to include the includeActions parameter in your method call with the value set true on in the request. For more information, see Actions and pagination.
IsNameAvailable
This endpoint has one implementation. To validate one or more name requests, send a POST request with one of the following URLs:
https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/install/conflict/validate-names |
GetAvailableWorkspacesAsync
This endpoint has two implementations with optional query fields start (default: 1), length (default: 10), and includeActions (default: false). To search application installations, send a POST request to one of the following URLs:
1 2 | https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationID:int}/install/available-workspaces?start={start}&length={length}&includeActions={includeActions} https: //{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid:guid}/install/available-workspaces?start={start}&length={length}&includeActions={includeActions} |
Note: The includeActions parameter controls whether the pagination properties are populated. If your workflow requires iterating through pages of results using these properties, you need to include the includeActions parameter in your method call with the value set true on in the request. For more information, see Actions and pagination.