Imaging API services for REST

The Imaging API provides multiple HTTP services used for programmatically interacting with imaging profiles, sets, jobs, and other related components through Representational State Transfer (REST). The REST endpoints on the imaging job service support running and canceling jobs, updating priorities on jobs, and retrying jobs with errors. Endpoints on the services for imaging profiles, imaging sets, and application field codes support all CRUD operations. The imaging set service provides additional functionality used to hide and release images during a quality control review, while the native type service includes an endpoint for reading native file types supported by Relativity.

Sample use cases for the imaging services include automating workflows and building custom applications with this functionality. For example, you could use the imaging services to automate a workflow for running imaging jobs rather than manually performing these tasks through the Relativity UI. You could implement an application with a custom UI that displays information about imaging profiles, imaging sets, and jobs based on specific requirements from your organization.

Additionally, you can also access the Imaging API services through .NET interfaces. These interfaces support the same functionality as available through REST. For more information, see Imaging API.

This page contains the following information:

See this related page:

Client code sample

You can use the .NET code samples provided in this section as a REST client for interacting with the imaging services. The URLs for the imaging services have the following general format:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/[Name of Object] Service\[Function name]

To interact with an endpoint on one of the imaging services, send an HTTP request that makes a POST method call. See the following base URLs for each of the services:

The following code sample illustrates how to set up the HttpClient object to make REST calls. The baseUri parameter uses the format: https://<Your-Relativity-Instance.com>/Relativity.REST/api/.

public static HttpClient GetHttpClient(string baseUri, string username, string password)
{
    HttpClient httpClient = new HttpClient();
    httpClient.BaseAddress = new Uri(baseUri);
    
    //Encode authorization for the header based on username and password.
    string usernamePassword = string.Format("{0}:{1}", username, password);
    string base64usernamePassword = Convert.ToBase64String(Encoding.ASCII.GetBytes(usernamePassword));
    httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
    httpClient.DefaultRequestHeaders.Add("Authorization", "Basic " + base64usernamePassword);
    return httpClient;
}

You can use the method in the next code sample to return a response. It takes the following parameters:

See the following code sample:

public static async Task<string> GetJsonResponse(HttpClient httpClient, string jsonToPost, string url)
{
  StringContent content = new StringContent(jsonToPost, Encoding.UTF8, "application/json");
  //All REST API methods use POST.
  HttpResponseMessage response = await httpClient.PostAsync(url, content);
  return await response.Content.ReadAsStringAsync();
}

Guidelines for imaging through REST

While the arguments for passing in JSON are case insensitive, we recommend that you follow capitalization rules used for reading requests and representing objects provided in the following code samples. For example, the SaveAsync methods on the imaging services takes the imagingObject and workspaceId parameters. This JSON sample illustrates the suggested construction of an object:

{
   "imagingObject":{
    "ObjectProperty1":      ...
    "ObjectProperty2":{
         "PropertyOfObjectProperty2":...
      }      ...
   },
   "workspaceId":123456
}

Imaging profiles

An imaging profile defines a set of options that you want to use when imaging a group of documents. It may include options for controlling how spreadsheets, emails, or other document types are imaged, such as page orientation, or other specialized settings. For more information, see Imaging profiles on the RelativityOne Documentation site.

Create or update an imaging profile

You can create imaging profiles by using options available on basic imaging engine or on the native imaging engine. Review the following guidelines for imaging profiles before creating these objects:

To create or update an imaging profile, send a request to the SaveAsync endpoint with this URL on the Imaging Profile Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/SaveAsync

When an imaging profile is successfully created or updated, the JSON response contains its Artifact ID, such as 1038842.

Retrieve an imaging profile

Use the ReadAsync endpoint to retrieve an imaging profile. Send a request to the following URL on the Imaging Profile Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/ReadAsync

The request must contain the following fields:

{
   "imagingProfileId":1038583,
   "workspaceID":1017048
}

The response contains the following fields:

Delete an imaging profile

Use the DeleteAsync endpoint to delete an imaging profile. Send a request to the following URL on the Imaging Profile Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/DeleteAsync

The request must contain the following fields:

{
   "imagingProfileId":1038583,
   "workspaceID":1017048
}

The response returns true when the imaging profile is successfully deleted.

Imaging sets

To running an imaging job, you need to create an imaging set, which consists of an imaging profile and a search containing the documents to image. The Imaging Sets Manager service supports create, read, update and delete operations on imaging sets. It also supports the hide and release operations used for a QC Review of imaged documents. For more information, see Imaging sets and QC Review on the RelativityOne Documentation site.

Create or update an imaging set

Use the SaveAsync endpoint for both creating and updating an imaging set. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/SaveAsync

The request must contain the following fields:

When an imaging set is successfully created or updated, the JSON response contains its Artifact ID, such as 1038842.

Retrieve an imaging set

Use the ReadAsync endpoint to retrieve an imaging set. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/ReadAsync

The request must contain the following fields:

{
   "imagingSetId":1038815,
   "workspaceID":1017048
}

The response returns the following fields:

{
   "ImagingProfile":{
      "ArtifactID":1038814
   },
   "DataSource":1038811,
   "EmailNotificationRecipients":"",
   "Status":{

   },
   "ArtifactID":1038815,
   "Name":"Imaging Set updated from REST"
}

Delete an imaging set

Use the DeleteAsync endpoint to delete an imaging set. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/DeleteAsync

The request must contain the following fields:

{
   "imagingSetId":1038815,
   "workspaceID":1017048
}

The response returns the status code of 200 when the image set is successfully deleted.

Hide an imaging set

You can hide images that need to undergo a quality control review from your reviewers. For more information, see QC Review on the RelativityOne Documentation site.

Use the HideImagingSetAsync endpoint to hide an imaging set from reviewers. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/HideImagingSetAsync

The request must contain the following fields:

{
   "imagingSet":{
      "imagingSetId":1039603,
      "Name":1017371
   },
   "workspaceId":1017048
}

The response returns the status code of 200 when the image set is successfully hidden.

Release an imaging set

After a quality control review has been completed on images, you can then programmatically make them available to reviewers by making a call to the ReleaseImagingSetAsync endpoint. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/ReleaseImagingSetAsync

The request must contain the following fields:

{
   "imagingSet":{
      "imagingSetId":1039603,
      "Name":1017371
   },
   "workspaceId":1017048
}

The response returns the status code of 200 when the image set is successfully released.

Native types

You can retrieve native file types supported by Relativity for imaging. For more information, see Imaging native types on the RelativityOne Documentation site.

Retrieve a native type

Use ReadAsync endpoint to retrieve a native type. Send a request to this URL on the Native Type Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Native Type Service/ReadAsync

The request must contain the following fields:

{
   "nativeTypeId":1036567,
   "workspaceID":1017048
}

The response returns the following fields:

{
   "BasicCategory":"WordProcessor",
   "NativeCategory":"WordProcessor",
   "UseNativeImaging":true,
   "RestrictedFromImagingByDefault":false,
   "FileTypeId":1336,
   "PreventNativeDownload":false,
   "ArtifactID":1036567,
   "Name":"Microsoft Word 2010"
}

Application field codes

Microsoft applications use fields codes as placeholders for data that may be updated or used for other specialized purposes in their documents, such as those created in Word, Excel, or others. In Relativity, application field codes indicate how to handle field codes used in Microsoft documents during imaging. You can programmatically create, read, update, or delete application field codes through the Application Field Code Manager service. For more information, see Application Field Codes on the RelativityOne Documentation site.

Create or update an application field code

Use the SaveAsync endpoint to create or update an application field code. Send a request to this URL on the Application Field Code Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/SaveAsync

The request must contain the following fields:

When an application field code is successfully created or updated, the JSON response contains its Artifact ID, such as 1038582.

Retrieve an application field code

Use the ReadAsync endpoint to retrieve an application field code. Send a request to this URL on the Application Field Code Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/ReadAsync

The request must contain the following fields:

{
   "applicationFieldCodeId":1038582,
   "workspaceID":1017048
}

The response returns the following fields:

{
   "FieldCode":"Date",
   "Application":"MicrosoftWord",
   "Option":"ShowFieldCode",
   "ArtifactID":1038582,
   "Name":"NewFieldCode"
}

Delete an application field code

Use the DeleteAsync endpoint to remove a specific application field code. Send a request to this URL on the Application Field Code Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/DeleteAsync

The request must contain the following fields:

{
  "applicationFieldCodeId": 1038582,
  "workspaceID": 1017048
}

The response returns true when the application field code is successfully deleted.

Imaging jobs

You can programmatically run jobs to image documents, cancel the job currently executing on an imaging set, or retry errors that occurred during a job. For general information, see Running an imaging set and Imaging errors on the RelativityOne Documentation site.

Run an imaging set job

Use the RunImagingSetAsync endpoint to start an imaging job. Send a request to this URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/RunImagingSetAsync

The request must contain the following fields:

Note: The QcEnabled property is an optional argument when constructing a new ImagingJob. If you don't specify it on the initial run of an imaging set, then it defaults to false. On subsequent runs, it defaults to the value used for the previous run. For more information, see Imaging API.

{
   "imagingJob":{
      "imagingSetId":1039603,
      "workspaceId":1017371
   }
}

The response returns the ImagingJobId field, which contains a GUID that uniquely identifies the job.

{
   "ImagingJobId":"442dd13d-26ed-493d-b48c-3547ef62394c"
}

Image a single document

Use the ImageDocumentAsync endpoint to image a single document rather than a group of them belonging to an imaging set. You can also image a native file stored in Relativity or specify an alternative native file by providing a file path for it.

Note: To an cancel an on-the-fly imaging job, use the StopImagingJobAsync endpoint.

Send a request to the following URL on the Imaging Job service:

<host>/Relativity.Rest/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/ImageDocumentAsync

In the JSON request, the following fields are required unless specifically identified as optional:

{  
   "imageDocumentJob":{  
      "WorkspaceId":1031808,
      "DocumentId":1053648,
      "ProfileId":1036462,
      "AlternateNativeLocation":"//fileshare/path/filename.ext",
      "RemoveAlternateNativeAfterImaging":"true"
   }
}

The response returns the ImagingJobId field, which contains a GUID that uniquely identifies the job.

{
   "ImagingJobId":"86367960-076a-47ea-8e24-1cd27135ed33"
}

Cancel imaging jobs

You can use the StopImagingJobAsync endpoint to cancel imaging jobs. The StopImagingJobAsync endpoint cancels any type of imaging job, including imaging set jobs.

Cancel an imaging job

Use the StopImagingJobAsync endpoint to cancel any imaging job, including an imaging set job and a job for imaging on the fly. Send a request to this URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/StopImagingJobAsync

The request must contain the following fields:

{
   "stopImagingJobRequest":{
      "imagingJobId":1054631,
      "workspaceArtifactId":1017371
   }
}

The response contains the following fields:

{
   "stopImagingJobResponse":{
      "success":true
   }
}

Retry imaging set errors

Use the RetryErrorsAsync endpoint to rerun an imaging job. Send a request to this URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/RetryErrorsAsync

The request must contain the following fields:

{
   "imagingJob":{
      "imagingSetId":1039603,
      "workspaceId":1017371
   }
}

The response returns the ImagingJobId field, which contains a GUID that uniquely identifies the job.

{
   "ImagingJobId":"c2f4503a-a14a-4b44-a3c0-cba58d16577a"
}

Update the priority of an imaging job

(Available in RelativityOne 10.2.170.2 and above)

Use the UpdateJobPriorityAsync endpoint to modify the priority for an imaging job in a specific workspace. Send a request to the following URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/UpdateJobPriorityAsync

The request must contain the following fields:

{
   "UpdateJobPriorityRequest":{
      "jobGuid":"2C0512A4-E56E-4B4F-A0B2-BAC351E13D2F",
      "priority":10,
      "workspaceId":1017371
   }
}

The JSON response contains the following fields:

{
   "updateJobPriorityResponse":{
      "updateJobPriorityResponse":true,
      "errorMessage":""
   }
}

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

   
Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget