This guide documents the InsightVM Cloud Integrations Application Programming Interface (API). This API supports the Representation State Transfer (REST) design pattern. See Insight Platform API Overview for an overview of all Insight Platform APIs.

Versioning is specified in the URL and the base path of this API is:

https://{region}.api.insight.rapid7.com/vm/{version}/

Version numbers are numerical and prefixed with the letter "v", such as "v4".

The region indicates the geo-location of the Insight Platform desired:

Authorization requires a token header X-Api-Key and can be generated from the Insight Platform key management page. See Insight Platform API Key for more details.

Unless noted otherwise this API accepts and produces the application/json and application/xml media types. Unless otherwise indicated, the default request body media type is application/json.

The following HTTP operations are supported throughout this API. The general usage of the operation and both its failure and success status codes are outlined below.

Dates & Times

Dates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input:

Timezones

Timezones are specified in the regional zone format, such as "America/Los_Angeles", "Asia/Tokyo", or "GMT".

Paging

Pagination may be supported on collection resources using a combination of two query parameters, page and size. The page parameter dictates the zero-based index of the page to retrieve, and the size indicates the size of the page.

For example, /resources?page=2&size=10 will return page 3, with 10 records per page, giving results 21-30.

The maximum page size for a request is 500.

Some paginated endpoints may supported "cursored" pages, allowing for a guaranteed consistent view of data across page boundaries. Cursored page requests support a consistent, sequential way to access data across pages. Only if this option is used are you guaranteed that you will read a record once and only once in any page ("repeatable read"). The cursor property is used to follow the same chain of paginated requests from page to page. Each request will change the value of the next cursor to use on the subsequent page, and may only be used to iterate sequentially through pages. Cursors are stateless (results may shift across page boundaries while they are being read as data updates) unless otherwise noted.

The response to a paginated request follows the format:

{
   data": [ 
      ... 
   ],
   "metadata": { 
      "number": ...,
      "size": ...,
      "sort": ...,
      "totalResources": ...,
      "totalPages": ...,
      "cursor": ...
   },
   "links": [ 
      "first" : {
         "href" : "..."
       },
       "prev" : {
         "href" : "..."
       },
       "self" : {
         "href" : "..."
       },
       "next" : {
         "href" : "..."
       },
       "last" : {
         "href" : "..."
       } 
   ]
}

The data property is an array of the resources being retrieved from the endpoint, each which should contain at minimum a "self" relation hypermedia link. The metadata property outlines the details of the current page and total possible pages. The object for the page includes the following properties:

• number - The page number (zero-based) of the page returned.
• size - The size of the pages, which is less than or equal to the maximum page size.
• totalResources - The total amount of resources available across all pages.
• totalPages - The total amount of pages.
• cursor - An optional cursor for "cursored" page requests

The last property of the paged response is the links array, which contains all available hypermedia links. For paginated responses, the "self", "next", "previous", "first", and "last" links are returned. The "self" link must always be returned and should contain a link to allow the client to replicate the original request against the collection resource in an identical manner to that in which it was invoked.

The "next" and "previous" links are present if either or both there exists a previous or next page, respectively. The "next" and "previous" links have hrefs that allow "natural movement" to the next page, that is all parameters required to move the next page are provided in the link. The "first" and "last" links provide references to the first and last pages respectively. If the page is "cursored" the cursor is automatically incorporated into the pagination links.

Sorting

Sorting is supported on paginated resources with the sort query parameter(s). The sort query parameter(s) supports identifying a single or multi-property sort with a single or multi-direction output. The format of the parameter is:

sort=property[,ASC|DESC]...

Therefore, the request /resources?sort=name,title,DESC would return the results sorted by the name and title descending, in that order. The sort directions are either ascending ASC or descending DESC. With single-order sorting, all properties are sorted in the same direction. To sort the results with varying orders by property, multiple sort parameters are passed.

For example, the request /resources?sort=name,ASC&sort=title,DESC would sort by name ascending and title descending, in that order.

The following response statuses may be returned by this API.

Errors

Any error responses can provide a response body with a message to the client indicating more information (if applicable) to aid debugging of the error. All 4xx and 5xx responses will return an error response in the body. The format of the response is as follows:

{
   "status": <statusCode>,
   "message": <message>,
   "localized_message": <message>,
   "links" : [ {
      "rel" : "...",
      "href" : "..."
    } ]
} 

The status property is the same as the HTTP status returned in the response, to ease client parsing. The message property is a localized message in the request client's locale (if applicable) that articulates the nature of the error. The last property is the links property.

Security

The response statuses 401, 403 and 404 need special consideration for security purposes. As necessary, error statuses and messages may be obscured to strengthen security and prevent information exposure. The following is a guideline for privileged resource response statuses:

Headers

Commonly used response headers include:

Format

When application/json is returned in the response body it is always pretty-printed (indented, human readable output). Additionally, gzip compression/encoding is supported on all responses.

Dates & Times

Dates or times are returned as strings in the ISO 8601 'extended' format. When a date and time is returned (instant) the value is converted to UTC.

For example:

Endpoints to discover available resources and operations in this API.

Endpoints to monitor service health and quality.

Resources and operations for managing assets.