REST API Overview

You can use the InsightOps REST API to automate common tasks by creating your own scripts to execute from the command line without needing to access the user interface. With the API, you can programmatically query your log data or interact with resources, such as logs, alerts, or saved queries.

You can perform the following actions with the API:

  • API Keys: Interact with your keys in the account.
  • Query API: Perform LEQL queries through an API interface in the same manner that you would in the UI.
  • Saved Queries: Interact with Saved Queries in your account.
  • Tags: Interact with Tags in your account.
  • Labels: Interact with labels for tags and alerts in your account.
  • Logs: Interact with Logs in your account.
  • Log Sets: Interact with Logs in your account.
  • Download Logs: Download and stream log events to your machine for the given log IDs and query parameters over HTTPS.
  • Usage: Access information on your data usage for your insightOps Account.

Requirements

Before using the API, you must:

  1. Obtain an API key.
  2. Review the supported regions.

Obtain an API key

Your API basepath and API keys vary based on what type of customer you are.

Migrated customers

Customers migrated from LogEntries have 2 options for getting API access. The option you choose determines the API basepath and access level.

**Use an InsightOps key. **

  • API Base Path - https://.rest.logs.insight.rapid7.com/
  • API Key - To obtain an API key, follow the steps in Generate a InsightOps API key.
  • Access Level - Read / Write, Read Only

**Use a Platform key. **

  • API Base Path - https://.api.insight.rapid7.com/log_search
  • API Key - To obtain an API key, follow the steps in Managing Platform API Keys.
  • Access Level - Organization or user key. A user key grants Read / Write or Read Only

Non-migrated Customers

Customers who are not migrated from LogEntries use the InsightOps key.

  • API Base Path - https://.rest.logs.insight.rapid7.com
  • API Key - To obtain an API key, follow the steps in Generate a InsightOps API key.
  • Access Level - Read / Write, Read Only

New Customers

New customers use the Platform key.

  • API Base Path - https://.rest.logs.insight.rapid7.com
  • API Key - To obtain an API key, follow the steps in Managing Platform API Keys.
  • Access Level - Organization or user key. A user key grants Read / Write or Read Only

Review the supported regions

Rapid7 supports the following regions for the API:

  • us: United States:
  • eu: Europe
  • ca: Canada
  • au: Australia
  • ap: Japan

In your API base path, update your region based on where you are located. For example, if you’re in Japan, your base path would be https://ap.rest.logs.insight.rapid7.com.

Rate limits

You can indicate a rate limit for the API, which sets how often you can make a request to the API in a specified amount of time. Requests are subject to rate limits within a 15 minute period, per API key on an API endpoint.

API response headers return the following information about rate limit information:

  • X-Rate-Limit-Remaining: the total number of requests remaining for this period.
  • X-Rate-Limit-Limit: the total number of requests allowed within this period.
  • X-Rate-Limit-Reset: the number of seconds until the remaining number of requests will be reset to the limit.

If you exceed the rate limit, the API will return an HTTP 429 error code (Too Many Requests) with a Retry-After header set that indicates how long (in seconds) you must wait before trying again.

Generate a InsightOps API key

To obtain an InsightOps API key:

  1. Sign in to InsightOps.
  2. Select the Settings page from the left menu.
  3. Select the API Keys tab.
  4. Choose which key you need, and then click the Copy button.
    • Read-only keys: Query your log events or retrieve a list of resources.
    • Read/Write keys: Add resources or configure the Insight Agent to follow logs.