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:
Code | Region |
---|---|
us | United States |
eu | Europe |
ca | Canada |
au | Australia |
ap | Japan |
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.
Verb |
Usage | Success | Failure |
---|---|---|---|
GET |
Used to retrieve a resource by identifier, or a collection of resources by type. | 200 |
400 , 401 , 402 , 404 , 405 , 408 , 410 , 415 , 500 |
POST |
Creates a resource with an application-specified identifier. | 201 |
400 , 401 , 404 , 405 , 408 , 413 , 415 , 500 |
POST |
Performs a request to queue an asynchronous job. | 202 |
400 , 401 , 405 , 408 , 410 , 413 , 415 , 500 |
PUT |
Creates a resource with a client-specified identifier. | 200 |
400 , 401 , 403 , 405 , 408 , 410 , 413 , 415 , 500 |
PUT |
Performs a full update of a resource with a specified identifier. | 201 |
400 , 401 , 403 , 405 , 408 , 410 , 413 , 415 , 500 |
DELETE |
Deletes a resource by identifier or an entire collection of resources. | 204 |
400 , 401 , 405 , 408 , 410 , 413 , 415 , 500 |
OPTIONS |
Requests what operations are available on a resource. | 200 |
401 , 404 , 405 , 408 , 500 |
Dates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input:
Value | Format | Notes |
---|---|---|
Date | YYYY-MM-DD | Defaults to 12 am UTC (if used for a date & time |
Date & time only | YYYY-MM-DD'T'hh:mm:ss[.nnn] | Defaults to UTC |
Date & time in UTC | YYYY-MM-DD'T'hh:mm:ss[.nnn]Z | |
Date & time w/ offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm | |
Date & time w/ zone-offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm[ |
Timezones are specified in the regional zone format, such as "America/Los_Angeles"
, "Asia/Tokyo"
, or "GMT"
.
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 requestsThe 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 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.
Status | Meaning | Usage |
---|---|---|
200 |
OK | The operation performed without error according to the specification of the request, and no more specific 2xx code is suitable. |
201 |
Created | A create request has been fulfilled and a resource has been created. The resource is available as the URI specified in the response, including the Location header. |
202 |
Accepted | An asynchronous task has been accepted, but not guaranteed, to be processed in the future. |
400 |
Bad Request | The request was invalid or cannot be otherwise served. The request is not likely to succeed in the future without modifications. |
401 |
Unauthorized | The user is unauthorized to perform the operation requested, or does not maintain permissions to perform the operation on the resource specified. |
403 |
Forbidden | The resource exists to which the user has access, but the operating requested is not permitted. |
404 |
Not Found | The resource specified could not be located, does not exist, or an unauthenticated client does not have permissions to a resource. |
405 |
Method Not Allowed | The operations may not be performed on the specific resource. Allowed operations are returned and may be performed on the resource. |
408 |
Request Timeout | The client has failed to complete a request in a timely manner and the request has been discarded. |
413 |
Request Entity Too Large | The request being provided is too large for the server to accept processing. |
415 |
Unsupported Media Type | The media type is not supported for the requested resource. |
500 |
Internal Server Error | An internal and unexpected error has occurred on the server at no fault of the client. |
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.
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:
Use Case | Access | Resource | Permission | Status |
---|---|---|---|---|
Unauthenticated access to an unauthenticated resource. | Unauthenticated | Unauthenticated | Yes | 20x |
Unauthenticated access to an authenticated resource. | Unauthenticated | Authenticated | No | 401 |
Unauthenticated access to an authenticated resource. | Unauthenticated | Non-existent | No | 401 |
Authenticated access to a unauthenticated resource. | Authenticated | Unauthenticated | Yes | 20x |
Authenticated access to an authenticated, unprivileged resource. | Authenticated | Authenticated | No | 404 |
Authenticated access to an authenticated, privileged resource. | Authenticated | Authenticated | Yes | 20x |
Authenticated access to an authenticated, non-existent resource | Authenticated | Non-existent | Yes | 404 |
Commonly used response headers include:
Header | Example | Purpose |
---|---|---|
Allow |
OPTIONS, GET |
Defines the allowable HTTP operations on a resource. |
Cache-Control |
no-store, must-revalidate |
Disables caching of resources (as they are all dynamic). |
Content-Encoding |
gzip |
The encoding of the response body (if any). |
Location |
Refers to the URI of the resource created by a request. | |
Transfer-Encoding |
chunked |
Specified the encoding used to transform response. |
Retry-After |
5000 | Indicates the time to wait before retrying a request. |
X-Content-Type-Options |
nosniff |
Disables MIME type sniffing. |
X-XSS-Protection |
1; mode=block |
Enables XSS filter protection. |
X-Frame-Options |
SAMEORIGIN |
Prevents rendering in a frame from a different origin. |
X-UA-Compatible |
IE=edge,chrome=1 |
Specifies the browser mode to render in. |
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 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:
Value | Format | Example |
---|---|---|
Date | YYYY-MM-DD |
2017-12-03 |
Date & Time | YYYY-MM-DD'T'hh:mm:ss[.nnn]Z |
2017-12-03T10:15:30Z |
Returns an indicator of the health of the API.
region required | string (Region) Enum: "us" "us2" "us3" "eu" "ca" "au" "ap" Example: us The region of the Insight Platform to use. See Overview for more information. |
object The details of the health of each component in the service (optional). | |
duration | string ${composite.health.summary.duration.description}, ${compositehealthsummary.duration.description} |
status | string Enum: "UP" "DOWN" "OUT-OF-SERVICE" "UNKNOWN" The status of the service. |
object (Health Summary) A summarization of the health of the service (optional). |
Healthy service response
{- "components": null,
- "status": "UP",
- "summary": null
}
Returns the inventory, assessment, and summary details for a page of assets. Only assets which the caller has access to are returned. If using the comparisonTime parameter, the recommended page size is 50.
region required | string (Region) Enum: "us" "us2" "us3" "eu" "ca" "au" "ap" Example: us The region of the Insight Platform to use. See Overview for more information. |
cursor | string Example: cursor=1549252222:::_S:::e3902e81-dcc3-37e2-981f-3ebc334f7122-default-asset-1158888 The stateless cursor to retrieve the next page of resources. |
currentTime | string Example: currentTime=2019-04-02T08:17:56.321Z The current date and time to compare against the asset state to detect changes. If specified, changes in vulnerabilities from this timestamp since the comparison time are calculated and output in the response. If not provided, defaults to the time of request. |
comparisonTime | string Example: comparisonTime=2018-11-09T08:17:56.321Z The date and time to compare the asset current state against to detect changes. If specified, changes in vulnerabilities from this timestamp to the current time are calculated and output in the response. If not provided, defaults to the current time value. |
includeSame | boolean Example: includeSame=false Whether the response should include the list of already-existing vulnerabilities on an asset. |
includeUniqueIdentifiers | boolean Example: includeUniqueIdentifiers=true Whether the response should include unique identifiers. |
page | integer Example: page=0 The index of the page (zero-based) to retrieve. |
size | integer Example: size=50 The number of records per page to retrieve. |
sort | string <<property>[,ASC|DESC]> Example: sort=id,ASC The criteria to sort the records by, in the format: |
Search query for filtering assets and vulnerabilities on assets.
asset | string Search criteria for filtering assets returned. |
vulnerability | string Search criteria for filtering vulnerabilities returned on each matching asset. |
Array of objects (Page Data) The page of resources returned. | |
Array of objects (Page Links) |