REST API reference

The REST API accepts and returns JSON.

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

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 https://mysystem.example.com:8000/auth/oauth/ \
-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..."

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" https://mysystem.example.com:<admin-app-port>
/api/admin/instances --header "Authorization: Bearer eyJr287bjle..."

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

$1=<server-name>

$2=<current-password>

$3=<new-password>

TOKEN=$(curl -ik -X POST https://$1.mysystem.com:8000/auth/oauth/ -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://$1.mysystem.com:8000/api/admin/setup/password -d ‘{“currentPassword” : “passw0rd”, “password” : “start123”}’

• To view the administrative REST API documentation, in the Admin App, click the help icon (). Then click Admin API.
• To view the search REST API documentation, in the Admin App, click the help icon (). Then click Search API.
• To view the workflow REST API documentation, in the Workflow Designer, click the help icon (). Then click Workflow API.
• To view the monitor REST API documentation, in the HCM application, click the user icon (). Then click Rest API.

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

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).

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.

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>
        }
    ]
}