Skip to main content

We've Moved!

Product Documentation has moved to
Hitachi Vantara Knowledge

REST API reference

Hitachi Content Intelligence gives these RESTful APIs:

  • An administrative REST API for managing the system. This interface allows you to perform all tasks relating to system setup, configuration, and indexing data (for example, creating and running workflows). Everything that you can do in the Admin App or you can also do with the admin REST API.
  • A search CLI for searching for files. Everything that you can do in the Search App you can also do with the search REST API.
  • A workflow REST API for creating and running workflows. Everything that you can do in the Workflow Designer you can also do with the workflow REST API.
  • A REST API for monitoring other systems. Everything that you can do in the Monitor App you can also do with the monitor REST API.

Input and output formats

The REST API accepts and returns JSON.

Access and authentication

To use the REST API, you need a user account that has permission to perform the actions you want.

Requesting an access token

After you have a user account, you need to request an authentication token from the system. To do this, you send an HTTP POST request to the /auth/oauth endpoint.

When you generate a new access token, a refresh token also gets generated automatically.

Here's an example using the cURL command-line tool:

curl -ik -X POST \
-d grant_type=password \
-d username=user1 \
-d password=password1 \
-d client_secret=my-client \
-d client_id=my-client \
-d realm=marketingUsers

In response to this request, you receive a JSON response body containing an access_token field. The value for this field is your token. For example:

{"access_token" : "eyJr287bjle..."
  • To get a list of security realms for the system, send an HTTP GET request to the /setup endpoint. For example, to do this with cURL:
    curl -k -X GET --header 'Accept: application/json' 
  • To get an access token for the local admin user account, you can omit the realm option for the request, or specify a realm value of Local.
Submitting your access token

You need to specify your access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with your request. Here's an example that uses cURL:

curl -X GET --header "Accept:application/json"<admin-app-port>
/api/admin/instances --header "Authorization: Bearer eyJr287bjle..."
Changing a password

You can use the REST API to change your system's password using the following cURL command.

TOKEN=$(curl -ik -X POST https://$ -d grant_type=password
 -d username=admin -d password=$2 -d client_secret=hci-client -d client_id=hci-client
 -d realm=local 2>&1  | grep access_token | awk -F: '{print $2}' | awk -F\" '{print $2}')
curl -v -X POST --header 'Content-Type: application/json' --header "Authorization: Bearer $TOKEN" 
https://$ -d ‘{“currentPassword” : “passw0rd”, “password” : “start123”}’
NoteThe currentPassword field is a required field.

Viewing and using REST API methods

Your system shows web-based documentation pages where you can view all supported REST API methods, including the request bodies, request URLs, response bodies, and return codes for each. You can also use these pages to run each REST API method.

Viewing the API documentation
  • To view the administrative REST API documentation, in the Admin App, click the help icon (GUID-A61DC5E9-1E5C-4D1E-9DBA-3B40B4C3158A-low.png). Then click Admin API.
  • To view the search REST API documentation, in the Admin App, click the help icon (GUID-A61DC5E9-1E5C-4D1E-9DBA-3B40B4C3158A-low.png). Then click Search API.
  • To view the workflow REST API documentation, in the Workflow Designer, click the help icon (GUID-A61DC5E9-1E5C-4D1E-9DBA-3B40B4C3158A-low.png). Then click Workflow API.
  • To view the monitor REST API documentation, in the HCM application, click the user icon (GUID-F65C10E6-C9EB-4958-9692-6E677A75CBF1-low.png). Then click Rest API.
Making requests


  1. Click the row for the method you want.

  2. If the method you want needs you to specify a UUID:

    1. Click the row for the GET method for the resource type that you want.

    2. Click Try it Out!.

    3. In the JSON response body, copy the value for the uuid field for the resource that you want.

      NoteIf you specify UUIDs when creating resources, the UUIDs are ignored.
  3. If the method you want needs you to specify a request body:

    1. In the Parameters section, under Model Schema, click inside the JSON text box.

      The JSON text is added to the Value field.
    2. Edit the JSON in the Value field.

      NoteSome methods might need other information in addition to or instead of UUIDs or JSON-formatted text. Some need particular string values or need you to browse for and select a file to upload.
  4. Click Try it out!.

Error responses

When an API request fails, the API returns:

  • An HTTP status code
  • Conditionally, an Hitachi Content Intelligence-specific error code
  • A JSON-formatted error response body
HTTP status codes

This table describes the typical reasons why these HTTP status codes are returned. For information on the status codes for a particular method, view the Hitachi Content Intelligence REST API web interface (see Viewing and using REST API methods).

Status codeDescription
400 (Bad Request)

The request body contains one or more of these:

  • An incorrect entry
  • An incorrect value for an entry
  • Incorrectly formatted JSON

If the request includes a UUID, the UUID might be incorrectly formatted.

403 (Forbidden)You do not have permission to perform the request.
404 (File not found)The resource you are trying to retrieve or edit cannot be found.
409 (Conflict)The resource you are trying to create already exists.
500 (Server Error)The system experienced an error.
Hitachi Content Intelligence-specific error codes

Some API requests return Hitachi Content Intelligence-specific error codes in addition to an HTTP status code. These error codes are listed in the errorCodes field in the JSON response body. This table describes these error codes.

Error codeDescription
4000SSL certificate not trusted.
4001The system license is expired.
JSON response body

REST API error responses have this format:

    "statusCode": <HTTP-status-code>,
    "errorCode": <Hitachi Content Intelligence-specific-error-code>,
    "errorMessage": <message>,
    "errorProperties": [
            "name": <error-property>,
            "message": <error-property-message>


  • Was this article helpful?