# Rapid7 Insight

> Read Rapid7 InsightVM assets, vulnerabilities and scans, and InsightIDR investigations, with a platform API key.

Lets an agent query the Rapid7 Insight Platform through its REST API: pull InsightVM assets, vulnerabilities and scans, and list, read and comment on InsightIDR investigations. Authentication is a single platform API key sent as the `X-Api-Key` header, scoped to your data region.

## What it can do

| Method | What it does |
| --- | --- |
| `rapid7_whoami` | Validate the API key and identify the caller (good first call). |
| `rapid7_vm_assets` | List InsightVM assets with host name, IP, OS, and risk score. |
| `rapid7_vm_vulnerabilities` | List InsightVM vulnerabilities with severity and CVSS. |
| `rapid7_vm_scans` | List InsightVM scan runs with status and timing. |
| `rapid7_idr_investigations_list` | List InsightIDR investigations (time range, statuses, paging). |
| `rapid7_idr_investigation_get` | Get one investigation with its alerts and timeline. |
| `rapid7_idr_investigation_comment` | Add a comment to an investigation. |
| `rapid7_request` | Generic passthrough to any product/endpoint for full API coverage. |

## How to get your key

Rapid7 authenticates calls with a **platform API key** sent in the `X-Api-Key` header.

1. Sign in to the [Rapid7 Insight Platform](https://insight.rapid7.com).
2. Open **Platform Settings** -> **API Keys** ([managing API keys](https://docs.rapid7.com/insight/managing-platform-api-keys)).
3. Create a **user key** (acts as you) or **organization key**, then copy it - it is shown only once.
4. Note your **data region** - the region your account lives in (it appears in your console URL): `us`, `us2`, `us3`, `eu`, `ca`, `au`, or `ap`.

## Fields to fill

| FlyMyAI field | Where it comes from |
| --- | --- |
| `RAPID7_API_KEY` | Platform Settings -> API Keys (user or organization key) |
| `RAPID7_REGION` | Your data region: `us`, `us2`, `us3`, `eu`, `ca`, `au`, or `ap` |

## Troubleshooting

- **`401 Unauthorized`** - the key is wrong or revoked. Re-create it under Platform Settings -> API Keys and re-paste it.
- **`403 Forbidden`** - the key's user/organization lacks access to that product (InsightVM vs InsightIDR) or asset. Use a key with the right entitlement.
- **Calls hit the wrong account or 404** - `RAPID7_REGION` is set to a different region than your account. Match it to the region in your console URL.
- **Empty InsightVM lists** - the integration API only returns data once a scan has run and assets exist. Confirm in the InsightVM console first.

## Links

- [Rapid7 Insight API overview](https://docs.rapid7.com/insight/api-overview)
- [Managing platform API keys](https://docs.rapid7.com/insight/managing-platform-api-keys)