Annotations Manager (REST)

In Relativity, markups refer to redactions and highlights that you can add to document images as part of the review process in the Image Viewer. A redaction obscures confidential content in an image, while a highlight visually emphasizes content. You can define the colors and styles used to add markups to a document image. For more information, see Image Viewer and Markups in the RelativityOne Documentation site.

The Annotations Manager service exposes functionality for programmatically redacting and highlighting document images. It contains methods for creating, updating, retrieving, and deleting redactions and highlights.

As a sample use case, you might use the this service in application that provides custom functionality for adding redactions or highlights to document images. You might include the ability to delete multiple redactions in a single operation.

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

Note: The following content uses the term annotations to reference redactions or highlights added to document images through the Image Viewer.

Guidelines for using the Annotations Manager service

Review the following guidelines for working with the Annotations Manager service.


The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set {versionNumber} to the version of the API, using the format lowercase v and the version number, such as v2.
  • Set other path parameters in the URLs to the Artifact ID of a given entity, such as {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 annotation:


Set the path parameters as follows:

  • {versionNumber} to the version of the service, such as v2.
  • {workspaceID} to the Artifact ID of the workspace containing the document image.
  • {documentID} to the Artifact ID of the document image.
  • {markUpSetID} to the Artifact ID of the markup set used to add the annotation.

Client code sample

To use the Annotations Manager service, send requests by making calls with the required HTTP methods. You can use the following .NET code as a sample client for retrieving annotations.

Create or update annotations

To create or update an annotation, send a POST request with a URL in the following format:


Note: Set the ID property on each Annotation object when making an update request.

Retrieve annotations on a document

To retrieve an annotation, send a GET request with a URL in the following format:


The request body is empty.

The response for a get operation contains the same fields as those for a create or update request. See the field descriptions for the request in View field descriptions for a create or update request.

Delete annotations from a document

To remove annotations, send a DELETE request with a URL in the following format:


The request body is empty.

When the annotations are successfully deleted, the response returns the status code of 200.