Command Platform API overview

The Command Platform provides an API that allows you to easily integrate your security solutions with Rapid7 products and solutions. It consists of several independent REST APIs that share a single endpoint, authentication mechanism, and design so that you can interact with Rapid7 products flexibly.

Endpoint

An API endpoint represents the location where the resource or data you are requesting lives. Most Command Platform APIs are accessible via a single centralized regional endpoint based on where you are located. For example, if you are in the United States, the regional endpoint is us.api.insight.rapid7.com.

To determine your endpoint, find the region code for the region that hosts your data. The easiest way to do this is by logging in to your Rapid7 account, accessing a Rapid7 product, and looking for the region code in the URL. The region code is the first two letters of the domain name. In the URL, us.idr.insight.rapid7.com, the region code is us. If you don’t see a region code, make sure you are accessing a specific product, such as InsightIDR, and not your Rapid7 account page.

Use the region code to determine your API endpoint: https://<REGION_CODE>.api.insight.rapid7.com. See Region Codes for more information.

Authentication

Authentication is performed by passing your API key via a single HTTP header: X-Api-Key. The key must be passed to all requests.

curl
1
curl -H "X-Api-Key: API_KEY" https://us.api.insight.rapid7.com/validate
2

3
HTTP/1.1 200 Success
4
{
5
  "message": "Authorized"
6
}

Failed login

Authenticating with invalid credentials will return a 401 Unauthorized message.

curl
1
curl -i -H "X-Api-Key: INVALID_API_KEY" https://us.api.insight.rapid7.com/validate
2

3
HTTP/1.1 401 Unauthorized
4
{
5
  "message": "Unauthorized"
6
}

Versioning

The Command Platform API consists of several individual REST APIs that share a common endpoint, authentication, and design patterns. Each individual API declares its own version. Backwards compatibility is preferred over API versioning and each API will only implement a new version for breaking changes.

Users are required to specify the API version in the URL.

For example:

text
1
 https://us.api.insight.rapid7.com/idr/v1/investigations
2

Pagination

Requests that return multiple items can be paginated. When a response is paginated, it will contain a metadata section describing the current page and a data section containing the response data.

For example:

text
1
{
2
  "data": [
3
    {"id": 3, "name": "vm-101"},
4
    {"id": 4, "name": "vm-102"}
5
  ],
6
  "metadata": {
7
    "index": 1,
8
    "size": 2,
9
    "total_pages": 4,
10
    "total_data": 7
11
  }
12
}
13

The metadata section may contain the following attributes:

• Index - The current page, starting from 0. This value will always be provided.
• Size - The number of data items in the current page. This value will always be provided.
• Total_pages - The total number of pages that make up the complete response. This will be provided if possible.
• Total_data - The total number of data items that make up the complete response. This will be provided if possible.
• Sort - The attributes used to sort the complete response. This will be provided if the response is sorted.

You can control which page is returned using query parameters.

For example:

text
1
https://us.api.insight.rapid7.com/idr/v1/investigations?index=3&size=50&sort=type,ASC,created,DESC

The query parameters used for pagination include:

• Index - The page to return, starting from 0.
• Size - The number of items to return per page.
  • The returned size may be smaller than the requested size in order to maintain API performance. Always check the metadata.size parameter in the response.
• Sort - The key,order pairs to sort by, separated by commas. The key is one of the supported sort keys for a given API. Order is one of ASC, for ascending, or DESC, for descending. Multiple sort keys can be provided by specifying multiple key,order pairs.
  • This may not be supported by some APIs. You can verify this from your product's API documentation.

Rate limiting

API requests may be rate limited. When rate limiting is in effect, the response will return headers to show your current rate limit status.

For example:

curl
1
curl -i -H "X-Api-Key: API_KEY" https://us.api.insight.rapid7.com/
2

3
HTTP/1.1 200 OK
4
RateLimit-Limit: 1000
5
RateLimit-Remaining: 412
6
RateLimit-Reset: 1531019617

The parameters for rate limiting include:

• RateLimit-Limit - The total number of requests you are permitted to make in the rate limit window. The rate limit window is typically 15 or 60 minutes, but varies by API.
• RateLimit-Remaining - The number of requests remaining in the current rate limit window.
• RateLimit-Reset - The time, in UTC epoch seconds, when the current rate limit window resets.

To ensure API performance is consistent for all customers, Rapid7 may change the rate limiting behavior at any time.

Retrieve Command Platform audit logs

If you have an organization-level API key or a Platform Admin user key, you can query logs using the REST API. With this functionality, you can query a single audit log or multiple audit logs.