Welcome to the Ivanti Security Controls REST API

This help system provides information to help you get started using the REST API feature in Ivanti Security Controls.

The API feature provides a simple RESTful interface with lightweight JSON-formatted responses that enables you to read and write data to/from the program. The feature allows you to automate many of your day-to-day operations, saving you considerable time and effort. The REST API allows you to fully integrate Ivanti Security Controls into your orchestration and automation systems. If you have any issues with the API or this documentation, contact Ivanti support.

Available Functions

Agents

Linux Patch Metadata

Patch Metadata

Agent Deployments

Linux Patch Scan Configuration

Patch Scans

Agent Tasks

Machines

Patch Scan Templates

Asset Scan Templates

Machine Groups

Policies

Cloud Synchronization

Operations

Product Level Group

Configuration

Patches

Session Credentials

Credentials

Patch Deployments

Users

Distribution Servers and IP Ranges

Patch Deployment Templates

Vendor Family Product Metadata

Linux Patch Deployment Configuration

Patch Downloads

Virtual Infrastructure

Linux Patch Groups

Patch Groups

Request URLs

The console machine will respond only to REST API requests that include proper authentication credentials. Authentication is by Windows challenge/response with Kerberos or NTLM.

Each resource collection in this RESTful API is identified by a unique URL. For example:

        https://<consoleFQDN:port>/st/console/api/v1.0/configuration/version

<consoleFQDN:port> is unique for each installation and represents the hostname of your console machine, your domain name and the port used to access the console. For example: mymachine.somedomain.com:3121.

v1.0 is the version specifier and must be present. When significant changes are made to the API (changes that would break compatibility with existing applications), this value will change.

Request/Response Format

All requests and responses are delivered in JavaScript Object Notation (JSON) format, a lightweight serialization language that is compatible with many different languages.

HTTP/HTTPS Methods

Standard HTTP/HTTPS methods are used to denote actions against a resource.

  • GET: Reads a resource
  • POST: Creates a new resource
  • PUT: Updates an entire resource
  • PATCH: Updates a portion of a resource
  • DELETE: Deletes a resource

Any web programming language (PowerShell, C++, Ruby, Python, C#, Java, etc.) can make and receive HTTP/HTTPS networking calls.

Always use a PUT when working with an existing resource. You will likely receive an error if you use a POST in an attempt to add a resource that already exists.

Standard Response Codes

Conventional HTTP/HTTPS response codes are used to indicate the success or failure of an API request.

  • 2xx range codes indicate success
    • 200: Success code
    • 204: Success code, no content. Used when there is no response body returned from the server.
  • 4xx range codes indicate an error that resulted from the caller-provided information (e.g. a required parameter was missing, a charge failed, etc.)
  • 5xx range codes indicate an error with the server

Error Policy

Errors are returned using standard HTTP/HTTPS error code syntax. Any additional information is included in the body of the return call in a JSON format.

You can specify how errors will be handled by adding an ErrorPolicy parameter to the body input of applicable requests.

  • ErrorPolicy=Throw means the entire request will be rejected.
  • ErrorPolicy=Omit means the problem area will be omitted, but the rest of the request will be completed. Omit is the default value.