Using the REST APIs

REST API enables developers to integrate data from TrueSight Server Automation with external applications. You can use the APIs to perform Create, Retrieve, Update, and Delete operations (CRUD) on the TrueSight Server Automation resources. For more information, see REST API endpoints.

The API follows the REST architectural style, so resources, HTTPS verbs, and status codes are used. This API uses standard HTTPS GET and POST methods to retrieve data from the server, and all responses from the server are in JavaScript Object Notation (JSON) format. The endpoints provided by the API are specified using the  Swagger  specification language. 

The REST APIs and Swagger UI support is available in TrueSight Server Automation or later versions.

API versions

The REST API is versioned separately from the TrueSight Server Automation. The API version provided with this version of the TrueSight Server Automationis version 1. You can find the version in the URL.





Content format

JSON is used for both request and response bodies. Each API request must include the following content-type parameter in the request header: 

accept: application/json


The timestamps for session and error responses are returned in ISO 8601 (YYYY-MM-DDTHH:MM:SS+HH:MM) format. Timestamps in all other response bodies are returned in YYYY-MM-DD HH:MM:SS HH:MM  format. The timestamp displayed is of the Application Server timezone.

JSON Responses

The response body contains the results of all requests. In addition to the requested content, the response body also contains status content that describes the success or failure of the request. 

  • Successful requests are indicated by returned 2xx HTTP status codes. 
  • Failed requests are indicated by returned 4xx (client error) or 5xx (server error) HTTP status codes. 

The response body also contains an object that contains details of the error, with the following fields:



timestampTime when the exception occurred


The HTTP request status code


The associated HTTP status message

messageThe error message
pathPath of the endpoint

Error response

Failed requests are indicated by returned 4xx (client error) or 5xx (server error) HTTP status codes. 

Here is an example request, resulting in the response 400 Bad Request:

  "timestamp": "2019-06-17T07:01:22.481+0000",
  "status": 400,
  "error": "Bad Request",
  "message": "#: required key [group] not found#:
required key [catalog] not found.",
  "path": "/rest/api/v1/patching-jobs/954"

Do not rely on error responses containing a body. In particular, authentication or permission failures often have empty bodies to avoid leaking information to the caller.

Status codes

The following table describes the status codes.

Error Code


200 OKThe request is accepted and results are returned.
201 CreatedA new resource is created after PUT or POST request.
202 AcceptedThe request is accepted for asynchronous processing.
204 No ContentThe request is completed but the server has no data to be displayed.
400 Bad RequestThe request was invalid. Either the URL is incorrect or the application specific constraints are violated.
401 Unauthorized

The client did not provide suitable authorization header. This error might occur in the following conditions:

  • A request to generate a token from /api/about with incorrect credentials, or for a user that has been deactivated.
  • A standard endpoint request that omits a valid, unexpired token.
403 Forbidden

Accessing the page or resource you are trying to reach is forbidden. This error occurs when the user does not have the required permission to perform the requested action.

404 Not FoundThe requested resource is not found.
405 Method not allowedThe method is not allowed by the web server for a requested URL.
500 Internal Server ErrorThe server encountered an unexpected error.


Several endpoints have the potential to return large amounts of data in their responses. These endpoints support a common approach for returning paginated results. Use the size request parameter to specify how many results are displayed on one page and thus how results should be returned. Use the page request parameter to specify which page should be returned.


curl -X GET "https://<hostname>:<port>/rest/api/v1/groups/server?page=4&size=20" -H "accept: application/json" -H "session-id: dbc1da51-2cd1-45a6-ad00-91dbab49bb54"

Here, the size parameter indicates the maximum number of items displayed on one page in the result. The page parameter indicates the page number. 

A paginated response includes a total_records in the response body. This count indicates how many results are available in total, which can aid you in asking for more pages, if, for example, you are implementing user-driven paged list display. Each API response will contain links to previousnextfirst, and the last page.

Was this page helpful? Yes No Submitting... Thank you


  1. Devendra Dehadaraya

    This page needs an update as there are lot of REST APIs as part of 21.02 - compliance-jobs, batch-jobs, rules, deploy, nshscript-jobs etc.

    Jan 18, 2021 07:06
    1. Bipin Inamdar

      I have removed this list and mentioned the REST API doc link to avoid duplication.

      Mar 17, 2021 08:21