Imaging API (REST)

Imaging API provides multiple HTTP services used for programmatically interacting with imaging profiles, sets, jobs, and other related components:

  • The services for imaging jobs include endpoints for running and canceling jobs, updating priorities on jobs, and retrying jobs with errors.
  • 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 functionality for reading native file types supported by Relativity.
  • Additional services provide endpoints for retrieving imaging status information for documents and managing your imaging environment.

Sample use cases for the imaging services include:

  • Use the imaging services to automate a workflow for running imaging jobs rather than manually performing these tasks through the Relativity UI.
  • Implement an application with a custom UI that displays information about imaging profiles, imaging sets, and jobs based on specific requirements from your organization.

You can also access the Imaging API services through .NET. For more information, see Imaging (.NET).

Note: The Imaging API is now versioned in the Osier release. The content on this page illustrates how to use this new versioned API. However, you can continue to use the legacy Imaging API with the Osier release although you should consider implementing any new functionality with the versioned Imaging API. For legacy documentation, see Imaging API on the Relativity Server 2021 Developers site.

Guidelines for the Imaging services

Review the following guidelines for working with these services.

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.
  • Note: To indicate the admin-level context, set the {workspaceID} path parameter to -1.

For example, you can use the following URL to retrieve an imaging profile:

Copy
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/{ImagingProfileID}

Set the path parameters as follows:

  • {versionNumber} to the version of the API, such as v1.
  • {WorkspaceID} to the Artifact ID of the workspace that contains the imaging profile.
  • {ImagingProfile} to the Artifact ID of a specific imaging profile.

Imaging Profile Manager

An imaging profile defines a set of options that you can 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.

The Imaging Profile Manager service supports create, read, update, and delete operations on imaging profiles.

Imaging Set Manager

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. For general information, see Imaging sets and QC Review on the RelativityOne Documentation site.

The Imaging Sets Manager API 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.

Native Type Manager

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

Application Field Code Manager

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. For more information, see Application Field Codes on the RelativityOne Documentation site.

Use the Application Field Code Manager service to create, read, update, or delete application field codes.

Imaging Job Manager

Use the Imaging Job Manager service to run jobs to image documents, cancel a 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.

Document Status Manager

Use the Document Status Manager service to obtain status information about the imaging job for a document.

Imaging Environment Manager

Use the endpoints on the Imaging Environment Manager service to remove inactive jobs and to obtain the size of mass imaging jobs.