{ "openapi": "3.1.0", "info": { "title": "InsightIDR API", "version": "v2", "description": "

Introduction

\n

Welcome to the reference documentation for the InsightIDR public APIs.

\n

Here are a few resources to help you learn how to start using our APIs:

\n\n

After you've got the basics down, you can use this API guide to find examples of requests and responses.

" }, "servers": [ { "url": "https://eu.api.insight.rapid7.com", "description": "Europe" }, { "url": "https://us.api.insight.rapid7.com", "description": "United States 1" }, { "url": "https://us2.api.insight.rapid7.com", "description": "United States 2" }, { "url": "https://us3.api.insight.rapid7.com", "description": "United States 3" }, { "url": "https://ca.api.insight.rapid7.com", "description": "Canada" }, { "url": "https://au.api.insight.rapid7.com", "description": "Australia" }, { "url": "https://ap.api.insight.rapid7.com", "description": "Japan" } ], "externalDocs": { "description": "Product docs", "url": "https://insightidr.help.rapid7.com/docs" }, "security": [], "tags": [ { "name": "Investigations", "description": "An API used to search, access, and modify investigations. To learn more about investigations, see our documentation at: https://docs.rapid7.com/insightidr/investigations" }, { "name": "Health Metrics", "description": "An API used to retrieve health metrics of an organization." } ], "paths": { "/idr/v2/investigations/{id}/status/{status}": { "put": { "tags": [ "Investigations" ], "summary": "Set the status of an investigation", "description": "An API that sets the status of the investigation, which is specified by id or rrn. This API returns the investigation with its status updated to the new state. If the investigation already has the given status, no change is made, but the investigation will still be returned.", "operationId": "setStatus", "parameters": [ { "name": "id", "in": "path", "description": "The id or rrn of the investigation to be changed.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "status", "in": "path", "description": "The new status for the investigation (case insensitive).", "required": true, "schema": { "type": "string", "enum": [ "OPEN", "CLOSED", "INVESTIGATING", "WAITING" ], "example": "OPEN" } }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationStatusRequestV2" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{id}/priority/{priority}": { "put": { "tags": [ "Investigations" ], "summary": "Set the priority of an investigation", "description": "An API that sets the priority of the investigation, which is specified by id or rrn. This API returns the investigation with its priority updated to the new state. If the investigation already has the given priority, no change is made, but the investigation will still be returned.", "operationId": "setPriority", "parameters": [ { "name": "id", "in": "path", "description": "The id or rrn of the investigation to be changed.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "priority", "in": "path", "description": "The new priority for the investigation (case insensitive).", "required": true, "schema": { "type": "string", "enum": [ "UNSPECIFIED", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "example": "MEDIUM" } }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{id}/disposition/{disposition}": { "put": { "tags": [ "Investigations" ], "summary": "Set the disposition of an investigation", "description": "An API that sets the disposition of the investigation, which is specified by id or rrn This API returns the investigation with its disposition updated to the new state. If the investigation already has the given disposition, no change is made, but the investigation will still be returned.", "operationId": "setDisposition", "parameters": [ { "name": "id", "in": "path", "description": "The id or rrn of the investigation to be changed.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "disposition", "in": "path", "description": "The new disposition for the investigation (case insensitive).", "required": true, "schema": { "type": "string", "enum": [ "BENIGN", "MALICIOUS", "NOT_APPLICABLE" ], "example": "BENIGN" } }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{id}/assignee": { "put": { "tags": [ "Investigations" ], "summary": "Assign user to investigation", "description": "An API that assigns a user to an investigation, specified by id or rrn. The user must be a platform administrator, product administrator, or read/write user with access to either InsightIDR or InsightUBA.", "operationId": "assignUserToInvestigation", "parameters": [ { "name": "id", "in": "path", "description": "The id or rrn of the investigation to assign the user to.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignUserToInvestigationRequestV2" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations": { "get": { "tags": [ "Investigations" ], "summary": "List investigations", "description": "An API that retrieves a page of investigations matching the given request parameters. By default, this page of investigations will be sorted by investigation priority in descending order.", "operationId": "listInvestigations", "parameters": [ { "name": "index", "in": "query", "description": "The 0-based index of the first page to retrieve. Must be an integer greater than 0.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "size", "in": "query", "description": "The maximum number of investigations to retrieve. Must be an integer greater than 0, or less than or equal to 100.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "statuses", "in": "query", "description": "A comma-separated list of investigation statuses to include in the result.", "required": false, "schema": { "type": "string" }, "example": "OPEN,INVESTIGATING,CLOSED" }, { "name": "sources", "in": "query", "description": "A comma-separated list of investigation sources to include in the result.", "required": false, "schema": { "type": "string" }, "example": "USER,ALERT" }, { "name": "priorities", "in": "query", "description": "A comma-separated list of investigation priorities to include in the result.", "required": false, "schema": { "type": "string" }, "example": "UNSPECIFIED, LOW, MEDIUM, HIGH, CRITICAL" }, { "name": "assignee.email", "in": "query", "description": "A user's email address. Only investigations assigned to that user will be included.", "required": false, "schema": { "type": "string" }, "example": "user@test.com" }, { "name": "start_time", "in": "query", "description": "The time an investigation is opened. Only investigations whose created_time is after this date will be returned by the API. Must be an ISO-formatted timestamp.", "required": false, "schema": { "type": "string", "default": "28 days prior" }, "example": "2018-07-01T00:00:00Z" }, { "name": "end_time", "in": "query", "description": "The time an investigation is closed. Only investigations whose created_time is before this date will be returned by the API. Must be an ISO-formatted timestamp.", "required": false, "schema": { "type": "string", "default": "The current time" }, "example": "2018-07-28T23:59:00Z" }, { "name": "sort", "in": "query", "description": "A field for investigations to be sorted by and their sort direction separated by a comma. Sortable fields are created_time,priority, rrn, alerts_most_recent_created_time, and alerts_most_recent_detection_created_time.", "required": false, "schema": { "type": "string", "default": "priority,DESC" } }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, a user API key must be provided. Investigations will be returned from all organizations the calling user has access to.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "tags", "in": "query", "description": "A comma-separated list of tags to include in the result. Only investigations who have all specified tags will be included.", "required": false, "schema": { "type": "string" }, "example": "Incident, Security Test, Reported to Customer, Potentially Unwanted Program" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageInvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Investigations" ], "summary": "Create investigation", "description": "An API to manually create investigations. Creating an investigation requires a user API key in the request headers. Non-default investigation fields can be specified in the request body. The API returns the newly created investigation information in the response.", "operationId": "createInvestigation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvestigationRequestV2" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{investigationRrn}/aisoc-clusters": { "post": { "tags": [ "Investigations" ], "summary": "Add aisoc clusters to an investigation", "description": "An API to associate one or more aisoc alert clusters with an existing investigation, specified by rrn. The request body is a list of alert cluster rrns. If every alert cluster is associated successfully, the API returns a 204. If one or more of the alert cluster rrns are already associated with a different investigation, the API returns a 207 (Multi-Status) response whose body contains the alert cluster rrns that were NOT added and the investigations they are associated with.", "operationId": "addAiSocClusters", "parameters": [ { "name": "investigationRrn", "in": "path", "description": "The rrn of the investigation to associate the alert clusters with.", "required": true, "schema": { "type": "string" }, "example": "rrn:investigation:us1:174e4f99-2ac7-4481-9301-4d24c34baf06:investigation:6A74T2A4" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "The rrns of the alert clusters to associate with the investigation.", "items": { "type": "string" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSocClusterInvestigationResponseV2" } } } }, "204": { "description": "No Content. All alert clusters were associated with the investigation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSocClusterInvestigationResponseV2" } } } }, "207": { "description": "One or more alert cluster rrns are associated to different investigations and were not added. The response body carries the association-conflict metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSocClusterInvestigationResponseV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Investigations" ], "summary": "Remove aisoc clusters from an investigation", "description": "An API to remove one or more aisoc alert clusters from an existing investigation, specified by rrn. The request body is a list of alert cluster rrns.", "operationId": "removeAiSocClusters", "parameters": [ { "name": "investigationRrn", "in": "path", "description": "The rrn of the investigation to remove the alert clusters from.", "required": true, "schema": { "type": "string" }, "example": "rrn:investigation:us1:174e4f99-2ac7-4481-9301-4d24c34baf06:investigation:6A74T2A4" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "The rrns of the alert clusters to remove from the investigation.", "items": { "type": "string" } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "204": { "description": "No Content. The alert clusters were removed from the investigation." }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/bulk_close": { "post": { "tags": [ "Investigations" ], "summary": "Close investigations in bulk", "description": "An API to bulk close all investigations that match the provided request parameters. This API returns the number of investigations that were closed and a list of their IDs.\n If there are any investigations found associated with Threat Command alerts within the given request parameters, they will be closed in Threat Command with the close reason, \"Other\".", "operationId": "bulkCloseInvestigations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCloseInvestigationsRequestV2" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosedInvestigationsV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/aisoc-clusters": { "post": { "tags": [ "Investigations" ], "summary": "Create investigation with aisoc clusters", "description": "An API to manually create an investigation and associate one or more aisoc alert clusters with it, optionally setting tags. Creating an investigation requires a user API key in the request headers. If every alert cluster is associated successfully, the API returns a 200 with the newly created investigation. If one or more of the provided alert cluster rrns are already associated with a different investigation, the API returns a 207 (Multi-Status) response whose body contains the newly created investigation rrn and the conflicting associations.", "operationId": "createAiSocClusterInvestigation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiSocClusterInvestigationRequestV2" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSocClusterInvestigationResponseV2" } } } }, "207": { "description": "The investigation was created but one or more alert cluster rrns are associated to different investigations and were not added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSocClusterInvestigationResponseV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/_search": { "post": { "tags": [ "Investigations" ], "summary": "Search investigations", "description": "An API that searches for investigations matching the given search/sort criteria.
FieldCan Search?Can Sort?TypeSearch Operator
actor_asset_hostnameYesNoStringCONTAINS
actor_user_nameYesNoStringCONTAINS
alert_mitre_t_codesYesNoStringEQUALS
alert_rule_rrnYesNoStringEQUALS
alerts_most_recent_created_timeNoYesStringN/A
alerts_most_recent_detection_created_timeNoYesStringN/A
assignee_idYesNoStringEQUALS
created_timeNoYesStringN/A
organization_idYesNoStringEQUALS
priorityYesYesStringEQUALS
rrnYesYesStringEQUALS
sourceYesNoStringEQUALS
statusYesNoStringEQUALS
titleYesNoStringCONTAINS
", "operationId": "searchInvestigations", "parameters": [ { "name": "index", "in": "query", "description": "The optional 0-based index of the page to retrieve. Must be an integer greater than or equal to 0. ", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "size", "in": "query", "description": "The optional size of the page to retrieve. Must be an integer greater than 0 or less than or equal to 100.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, a user API key must be provided. Investigations will be returned from all organizations the calling user has access to.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatedSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageInvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{id}": { "get": { "tags": [ "Investigations" ], "summary": "Get investigation", "description": "An API to retrieve a specific investigation. This investigation is specified by either id or rrn.", "operationId": "getInvestigationById", "parameters": [ { "name": "id", "in": "path", "description": "The id or rrn of the investigation to get investigation details.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Investigations" ], "summary": "Update investigation", "description": "An API that updates multiple fields in a single operation for an investigation, specified by id or rrn. The investigation will be returned with its changed fields. Null or omitted fields will not have their values updated in the investigation.", "operationId": "updateInvestigation", "parameters": [ { "name": "id", "in": "path", "description": "The id or rrn of the investigation to update", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvestigationRequestV2" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigationV2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{identifier}/rapid7-product-alerts": { "get": { "tags": [ "Investigations" ], "summary": "Get a list of Rapid7 product alerts associated with the specified investigation", "description": "An API to retrieve and list all Rapid7 product alerts associated with an investigation with the given id. These alerts are generated by Rapid7 products other than InsightIDR that you have an active license for.", "operationId": "getInvestigationRapid7ProductAlertInfo", "parameters": [ { "name": "identifier", "in": "path", "description": "The ID of the investigation.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecondPartyInfoDtoV2" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{identifier}/alerts": { "get": { "tags": [ "Investigations" ], "summary": "List alerts associated with the specified investigation", "description": "An API to retrieve and list all alerts associated with an investigation, with the given id or rrn. The listed alerts are sorted in descending order by alert create time.", "operationId": "listInvestigationAlerts", "parameters": [ { "name": "identifier", "in": "path", "description": "The ID of the investigation.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "index", "in": "query", "description": "The optional 0-based index of the page to retrieve. Must be an integer greater than or equal to 0.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "size", "in": "query", "description": "The optional size of the page to retrieve. Must be an integer greater than 0, or less than or equal to 100.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageInvestigationAlertDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/investigations/{identifier}/alerts/{alertRrn}": { "delete": { "tags": [ "Investigations" ], "summary": "Remove alert associated to an investigation", "description": "An API that removes the association between an alert and an investigation, which is specified by id or rrn. If the investigation is not associated with the given alert, not found exception will be thrown.", "operationId": "removeAlertFromInvestigation", "parameters": [ { "name": "identifier", "in": "path", "description": "The id or rrn of the investigation to be changed.", "required": true, "schema": { "type": "string" }, "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, { "name": "alertRrn", "in": "path", "description": "The rrn of the alert to be removed from the investigation.", "required": true, "schema": { "type": "string" }, "example": "rrn:alerts:us1:cf946362-0809-426d-987c-jkasdckjasb:alert:1:iuasdb11" }, { "name": "multi-customer", "in": "query", "description": "Indicates whether the requester has multi-customer access. If set to true, the ID of the investigation must be in the RRN format, the region of the RRN must match the region of the endpoint, and a user API key must be provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/idr/v2/health-metrics": { "get": { "tags": [ "Health Metrics" ], "summary": "Retrieve health metrics by org", "description": "Retrieve paginated health metrics for the given org. In the event of a 207 response, there may be two additional metadata fields in the response. 'failed_to_load' contains the the resource types that did not successfully load. 'unlicensed_resource_types' contains resource types that were requested, but for which the org does not have access to. ", "operationId": "getMetricsV2", "parameters": [ { "name": "index", "in": "query", "description": "The optional, 0 based index of the page to retrieve. Must be an integer greater than or equal to 0.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "example": 0 }, { "name": "size", "in": "query", "description": "The optional size of the page to retrieve. Must be an integer greater than 0 or less than or equal to 100.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "example": 20 }, { "name": "resourceTypes", "in": "query", "description": "An optional, comma-separated set of resource types. Only resources whose type matches one of the entries in the list are returned. If this parameter is omitted, health metrics with any resource type may be returned.", "required": false, "schema": { "type": "string" }, "example": "agent,collectors" }, { "name": "orgId", "in": "query", "description": "Optional organization ID to get metrics for. If not specified, metrics for the user's current organization will be returned. User must have access to the specified organization.", "required": false, "schema": { "type": "string" } }, { "name": "withEpm", "in": "query", "description": "Optional flag to include events per minute (EPM) for event sources. If true, performance of the API may be reduced.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageHealthMetricsV2" }, "examples": { "Agent": { "description": "Health metrics for agent resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:agent:678", "offline": 5, "online": 25, "stale": 3, "total": 33 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Collectors": { "description": "Health metrics for collector resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:collector:abc123", "id": "collector-001", "name": "Main Collector", "state": "RUNNING", "last_active": "2025-09-18T10:30:00Z", "event_sources_used": 15, "max_event_sources": 100, "memory_used": 2048, "max_memory": 4096, "percent_cpu_used": 25.5, "hostname": "example.rapid7.com", "ip_address": "192.0.2.0" } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Data Exporters": { "description": "Health metrics for data exporter resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:data_exporter:exporter001", "name": "Main Data Exporter", "state": "RUNNING", "last_active": "2025-09-18T10:30:00Z" } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Event Sources": { "description": "Health metrics for event source resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:event_source:source001", "name": "Main Event Source", "state": "ACTIVE", "last_active": "2025-09-18T10:30:00Z", "events_per_minute": 100 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Honeypots": { "description": "Health metrics for honeypot resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:honeypot:honeypot001", "id": "honeypot-001", "name": "Main Honeypot", "state": "ACTIVE", "last_active": "2025-09-18T10:30:00Z", "memory_used": 512, "max_memory": 1024, "percent_cpu_used": 10.5 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Orchestrator": { "description": "Health metrics for orchestrator resource", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:orchestrator:orch001", "name": "Main Orchestrator", "state": "RUNNING", "last_active": "2025-09-18T10:30:00Z", "cpu_used": 35.8, "memory_used": 3072, "max_memory": 6144, "storage_used": 20971520, "max_storage": 52428800, "hostname": "example.rapid7.com", "ip_address": "192.0.2.0" } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Scan Engines": { "description": "Health metrics for scan engine resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:scan_engine:engine001", "name": "Main Scan Engine", "state": "RUNNING", "storage_used": 52428800, "max_storage": 104857600, "last_active": "2025-09-18T10:30:00Z", "memory_used": 4096, "max_memory": 8192, "percent_cpu_used": 45.2 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Sensors": { "description": "Health metrics for sensor resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:sensor:sensor001", "name": "Main Sensor", "state": "ACTIVE", "health_status": [ "OK", "MONITORING" ], "storage_used": 15728640, "max_storage": 104857600, "last_active": "2025-09-18T10:30:00Z", "memory_used": 1024, "max_memory": 2048, "percent_cpu_used": 15.2, "drop_rate": 0.01 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } } } } } }, "207": { "description": "Multi-Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageHealthMetricsV2" }, "examples": { "Agent": { "description": "Health metrics for agent resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:agent:678", "offline": 5, "online": 25, "stale": 3, "total": 33 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Collectors": { "description": "Health metrics for collector resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:collector:abc123", "id": "collector-001", "name": "Main Collector", "state": "RUNNING", "last_active": "2025-09-18T10:30:00Z", "event_sources_used": 15, "max_event_sources": 100, "memory_used": 2048, "max_memory": 4096, "percent_cpu_used": 25.5, "hostname": "example.rapid7.com", "ip_address": "192.0.2.0" } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Data Exporters": { "description": "Health metrics for data exporter resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:data_exporter:exporter001", "name": "Main Data Exporter", "state": "RUNNING", "last_active": "2025-09-18T10:30:00Z" } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Event Sources": { "description": "Health metrics for event source resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:event_source:source001", "name": "Main Event Source", "state": "ACTIVE", "last_active": "2025-09-18T10:30:00Z", "events_per_minute": 100 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Honeypots": { "description": "Health metrics for honeypot resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:honeypot:honeypot001", "id": "honeypot-001", "name": "Main Honeypot", "state": "ACTIVE", "last_active": "2025-09-18T10:30:00Z", "memory_used": 512, "max_memory": 1024, "percent_cpu_used": 10.5 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Orchestrator": { "description": "Health metrics for orchestrator resource", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:orchestrator:orch001", "name": "Main Orchestrator", "state": "RUNNING", "last_active": "2025-09-18T10:30:00Z", "cpu_used": 35.8, "memory_used": 3072, "max_memory": 6144, "storage_used": 20971520, "max_storage": 52428800, "hostname": "example.rapid7.com", "ip_address": "192.0.2.0" } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Scan Engines": { "description": "Health metrics for scan engine resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:scan_engine:engine001", "name": "Main Scan Engine", "state": "RUNNING", "storage_used": 52428800, "max_storage": 104857600, "last_active": "2025-09-18T10:30:00Z", "memory_used": 4096, "max_memory": 8192, "percent_cpu_used": 45.2 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } }, "Sensors": { "description": "Health metrics for sensor resources", "value": { "data": [ { "rrn": "rrn:rapid7:us:customer:12345:sensor:sensor001", "name": "Main Sensor", "state": "ACTIVE", "health_status": [ "OK", "MONITORING" ], "storage_used": 15728640, "max_storage": 104857600, "last_active": "2025-09-18T10:30:00Z", "memory_used": 1024, "max_memory": 2048, "percent_cpu_used": 15.2, "drop_rate": 0.01 } ], "metadata": { "index": 0, "size": 1, "total_pages": 1, "total_data": 1 } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthMetricsErrorResponse" } } } } } } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "A human-readable message describing the error that occurred.", "example": "A human-readable message describing the error that occurred." }, "correlation_id": { "type": "string", "description": "An identifier that uniquely identifies the failed request.", "example": "An identifier that uniquely identifies the failed request." }, "additional_details": { "type": "object", "additionalProperties": {}, "description": "Additional structured error details forwarded from a downstream service, when available." } }, "required": [ "message" ] }, "InvestigationStatusRequestV2": { "type": "object", "description": "Additional info to set when setting an investigation's status.", "properties": { "disposition": { "type": "string", "description": "A disposition to set the investigation to. Only used if the new status is CLOSED. Defaults to UNDECIDED upon creation.", "enum": [ "BENIGN,MALICIOUS,NOT_APPLICABLE" ], "example": "BENIGN" }, "threat_command_close_reason": { "type": "string", "description": "The Threat Command reason for closing, applicable only if the investigation being closed has an associated alert in Threat Command. The Close Reason description depends on the Threat Command alert type. To get this information, use: `getInvestigationRapid7ProductAlertInfo`.", "enum": [ "ProblemSolved, InformationalOnly, ProblemWeAreAlreadyAwareOf, NotRelatedToMyCompany, FalsePositive, LegitimateApplication/Profile, CompanyOwnedDomain, Other" ], "example": "FalsePositive" }, "threat_command_free_text": { "type": "string", "description": "Additional information provided by the user when closing a Threat Command alert.", "example": "False positive alert" } } }, "InvestigationV2": { "type": "object", "properties": { "rrn": { "$ref": "#/components/schemas/RRN", "description": "The rrn of the investigation.", "example": "rrn:investigation:us1:174e4f99-2ac7-4481-9301-4d24c34baf06:investigation:6A74T2A4" }, "organization_id": { "type": "string", "writeOnly": true }, "title": { "type": "string", "description": "The name of the investigation.", "example": "Jane Smith enabled account Roger Johnson" }, "source": { "type": "string", "description": "How this investigation was generated.", "enum": [ "MANUAL,HUNT,ALERT" ], "example": "ALERT" }, "status": { "type": "string", "description": "The status of the investigation.", "enum": [ "OPEN,CLOSED,INVESTIGATING" ], "example": "OPEN" }, "priority": { "type": "string", "description": "The investigations priority.", "enum": [ "CRITICAL,HIGH,MEDIUM,LOW,UNSPECIFIED" ], "example": "CRITICAL" }, "last_accessed": { "type": "string", "writeOnly": true }, "created_time": { "type": "string", "writeOnly": true }, "disposition": { "type": "string", "description": "The disposition of this investigation.", "enum": [ "BENIGN,MALICIOUS,NOT_APPLICABLE,UNDECIDED" ], "example": "BENIGN" }, "assignee": { "type": [ "string", "null" ], "description": "Information about the user assigned to this investigation (if any)." }, "first_alert_time": { "type": [ "string", "null" ], "writeOnly": true }, "latest_alert_time": { "type": [ "string", "null" ], "writeOnly": true }, "tags": { "type": [ "array", "null" ], "description": "The tags assigned to this investigation (if any).", "example": [ "Incident", "Security Test" ], "items": { "type": "string" }, "uniqueItems": true }, "responsibility": { "type": [ "string", "null" ], "description": "The responsibility of the investigation, which denotes who is responsible for performing the investigation. This field will only appear for Managed Detection & Response customers.", "example": "CUSTOMER" }, "organizationId": { "type": "string", "description": "The id of the organization that owns this investigation.", "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, "lastAccessed": { "type": "string", "description": "The time this investigation was last viewed or modified.", "example": "2018-06-06T16:56:42Z" }, "createdTime": { "type": "string", "description": "The time this investigation was created.", "example": "2018-06-06T16:56:42Z" }, "firstAlertTime": { "type": "string", "description": "The create time of the first alert belonging to this investigation (if any).", "example": "2018-06-06T16:56:42Z" }, "latestAlertTime": { "type": "string", "description": "The create time of the most recent alert belonging to this investigation (if any).", "example": "2018-06-06T16:56:42Z" } }, "required": [ "createdTime", "disposition", "lastAccessed", "organizationId", "priority", "rrn", "source", "status", "title" ] }, "RRN": { "type": "object", "properties": { "partition": { "type": "string" }, "service": { "type": "string" }, "regionCode": { "type": "string" }, "organizationId": { "type": "string" }, "resourceTypes": { "type": "array", "items": { "type": "string" } }, "resource": { "type": "string" } } }, "AssignUserToInvestigationRequestV2": { "type": "object", "description": "Details about which user to assign.", "properties": { "user_email_address": { "type": "string", "description": "The email address of the user to assign to this investigation, used to log into the insight platform. ", "example": "example@test.com", "minLength": 1 } }, "required": [ "user_email_address" ] }, "AssigneeRequestV2": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the user to assign to this investigation, used to log into the insight platform. ", "example": "example@test.com" } }, "required": [ "email" ] }, "CreateInvestigationRequestV2": { "type": "object", "description": "This is the field information for the new investigation.", "properties": { "title": { "type": "string", "description": "The name of the investigation.", "example": "jsmith enabled account rroe", "minLength": 1 }, "status": { "type": "string", "description": "The status of the investigation. Defaults to OPEN.", "enum": [ "OPEN,CLOSED,INVESTIGATING" ], "example": "OPEN, CLOSED" }, "priority": { "type": "string", "description": "The priority for the investigation. Defaults to UNSPECIFIED.", "enum": [ "UNSPECIFIED,LOW,MEDIUM,HIGH,CRITICAL" ], "example": "UNSPECIFIED, LOW, MEDIUM, HIGH, CRITICAL" }, "disposition": { "type": "string", "description": "The disposition for the investigation. Defaults to UNDECIDED.", "enum": [ "UNDECIDED,BENIGN,MALICIOUS,NOT_APPLICABLE" ], "example": "UNDECIDED, BENIGN, MALICIOUS, NOT_APPLICABLE" }, "assignee": { "$ref": "#/components/schemas/AssigneeRequestV2", "description": "The user assigned to this investigation." } }, "required": [ "title" ] }, "AiSocClusterInvestigationResponseV2": { "type": "object", "properties": { "investigation": { "$ref": "#/components/schemas/InvestigationV2", "description": "The created AISOC cluster investigation. Present when the investigation was created." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Association-conflict metadata identifying the alert cluster rrns that were NOT added and the investigations they are associated with. Present only on a partial (207) response." } } }, "BulkCloseInvestigationsRequestV2": { "type": "object", "description": "The criteria for what investigations to close.", "properties": { "source": { "type": "string", "description": "The name of an investigation source. Only investigations from this source will be closed. If the source is ALERT, an alert type or a detection rule RRN must be specified as well.", "enum": [ "ALERT,MANUAL,HUNT" ], "example": "ALERT" }, "alert_type": { "type": "string", "description": "The category of types of alerts that should be closed. This parameter is required if the source is ALERT and ignored for other sources. This description must exactly match the alert type returned by the List Investigations response.", "example": "Attacker Behavior Detected" }, "disposition": { "type": "string", "description": "A disposition to set the investigation to. Defaults to NOT_APPLICABLE.", "enum": [ "UNDECIDED,BENIGN,MALICIOUS,NOT_APPLICABLE" ], "example": "BENIGN" }, "detection_rule_rrn": { "type": "string", "description": "The rrn of the detection rule. Only investigations that are associated with this detection rule will be closed. If a detection rule rrn is given, the alert_type is required to be 'Attacker Behavior Detected'.", "example": "rrn:cba:us1:a2c78570-5346-4d76-b57a-230da72c5e58:detection-rule:ABSJB123U3O9" }, "from": { "type": "string", "description": "The time investigations are to be closed from. Only investigations whose createTime is after this date will be closed. Must be an ISO-formatted timestamp.", "example": "2018-07-01T00:00:00Z" }, "to": { "type": "string", "description": "The time investigations are to be closed by. Only investigations whose created_time is before this date will be closed. Must be an ISO-formatted timestamp.", "example": "2018-07-08T00:00:00Z" }, "max_investigations_to_close": { "type": "integer", "format": "int32", "description": "An optional maximum number of alerts to close with this request. If this parameter is not specified then there is no maximum. If this limit is exceeded, then a 400 error response is returned. The minimum description is 0.", "enum": [ "range[0, infinity]" ], "example": 10 } }, "required": [ "from", "source", "to" ] }, "ClosedInvestigationsV2": { "type": "object", "properties": { "ids": { "type": "array", "description": "The ids of the investigations that were closed by the request.", "example": [ "581134c9-2510-4010-865c-7ae81761315b", "114c706d-e64a-4731-997b-9115beef3026" ], "items": { "type": "string" }, "uniqueItems": true }, "num_closed": { "type": "integer", "format": "int32", "description": "The number of investigations closed by the request.", "example": 2 } }, "required": [ "ids", "num_closed" ] }, "CreateAiSocClusterInvestigationRequestV2": { "type": "object", "description": "This is the field information for the new investigation.", "properties": { "title": { "type": "string", "description": "The name of the investigation.", "example": "jsmith enabled account rroe", "minLength": 1 }, "status": { "type": "string", "description": "The status of the investigation. Defaults to OPEN.", "enum": [ "OPEN,CLOSED,INVESTIGATING" ], "example": "OPEN, CLOSED" }, "priority": { "type": "string", "description": "The priority for the investigation. Defaults to UNSPECIFIED.", "enum": [ "UNSPECIFIED,LOW,MEDIUM,HIGH,CRITICAL" ], "example": "UNSPECIFIED, LOW, MEDIUM, HIGH, CRITICAL" }, "disposition": { "type": "string", "description": "The disposition for the investigation. Defaults to UNDECIDED.", "enum": [ "UNDECIDED,BENIGN,MALICIOUS,NOT_APPLICABLE" ], "example": "UNDECIDED, BENIGN, MALICIOUS, NOT_APPLICABLE" }, "assignee": { "$ref": "#/components/schemas/AssigneeRequestV2", "description": "The user assigned to this investigation." }, "alert_cluster_rrns": { "type": "array", "description": "The rrns of the alert clusters to associate with this investigation.", "example": [ "rrn:clusters:us1:73406292-d1b1-4ca0-a84f-1571fcf79c12:cluster:yQcUBPcW" ], "items": { "type": "string" } } }, "required": [ "title" ] }, "DatedSearchRequest": { "type": "object", "description": "The criteria and sorting information for searching. Includes date filtering information.", "properties": { "search": { "type": "array", "description": "The criteria for which entities to return.", "items": { "$ref": "#/components/schemas/SearchRequestCriteria" } }, "sort": { "type": "array", "description": "The sorting information.", "items": { "$ref": "#/components/schemas/SearchRequestSort" } }, "start_time": { "type": "string", "description": "An optional ISO formatted timestamp for the start of the time period to search for matching investigations. Only investigations whose created_time is after this date will be returned. If this field is omitted, this field will default to 28 days ago.", "example": "2018-07-04T00:00:00Z" }, "end_time": { "type": "string", "description": "An optional ISO formatted timestamp for the end of the time period to search for matching investigations. Only investigations whose created_time is before this date will be returned. If this field is omitted, the field will default to the current time. ", "example": "2018-07-04T00:00:00Z" } } }, "SearchRequestCriteria": { "type": "object", "properties": { "field": { "type": "string", "description": "The field to search within.", "example": "name" }, "operator": { "type": "string", "description": "The search operation to perform. All operators are case-insensitive when operating on Strings", "enum": [ "EQUALS,CONTAINS,IN" ] }, "value": { "description": "The value to search for." } } }, "SearchRequestSort": { "type": "object", "properties": { "field": { "type": "string", "description": "The field to sort by.", "example": "name" }, "order": { "type": "string", "description": "The sorting direction. Sorting is case-insensitive when sorting Strings.", "enum": [ "ASC,DESC" ] } } }, "PageInvestigationV2": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of data that matches the pagination parameters. If no results match, this will be an empty list.", "items": { "$ref": "#/components/schemas/InvestigationV2" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata", "description": "The pagination parameters used to generate this page result. " } }, "required": [ "data", "metadata" ] }, "PageMetadata": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32", "description": "The 0 based index of the page retrieved. ", "example": 0 }, "size": { "type": "integer", "format": "int32", "description": "The size of the page requested. ", "example": 20 }, "total_pages": { "type": "integer", "format": "int32", "description": "The total number of pages available with the given filter parameters. ", "example": 1 }, "total_data": { "type": "integer", "format": "int64", "description": "The total number of results available with the given filter parameters. ", "example": 15 } }, "required": [ "index", "size", "total_data", "total_pages" ] }, "UpdateInvestigationRequestV2": { "type": "object", "description": "The updates to the investigation fields.", "properties": { "title": { "type": "string", "description": "The new name of the investigation. The title will not update if omitted.", "example": "jsmith enabled account rroe" }, "status": { "type": "string", "description": "The new status for the investigations. The status will not update if omitted.", "enum": [ "OPEN,INVESTIGATING,CLOSED" ], "example": "OPEN" }, "priority": { "type": "string", "description": "The new priority for the investigation. The priority will not update if omitted.", "enum": [ "UNSPECIFIED,LOW,MEDIUM,HIGH,CRITICAL" ], "example": "HIGH" }, "disposition": { "type": "string", "description": "The new disposition for the investigation. The disposition will not update if omitted.", "enum": [ "BENIGN,MALICIOUS,NOT_APPLICABLE" ], "example": "BENIGN" }, "assignee": { "$ref": "#/components/schemas/AssigneeRequestV2", "description": "The new user assigned to this investigation. To unassign a user, set email to null. The assignee will not update if the object is null or omitted." }, "threat_command_close_reason": { "type": "string", "description": "The Threat Command reason for closing, applicable only if the investigation being closed has an associated alert in Threat Command. The Close Reason description depends on the Threat Command alert type. To get this information, use: `getInvestigationRapid7ProductAlertInfo`.", "enum": [ "ProblemSolved, InformationalOnly, ProblemWeAreAlreadyAwareOf, NotRelatedToMyCompany, FalsePositive, LegitimateApplication/Profile, CompanyOwnedDomain, Other" ], "example": "FalsePositive" }, "threat_command_free_text": { "type": "string", "description": "Additional information provided by the user when closing a Threat Command alert.", "example": "False positive alert" } } }, "GenericSecondPartyInfoDto": { "type": "object", "properties": { "product": { "type": "string", "description": "The product identifier for the Rapid7 product alert.", "example": "EXAMPLE_PRODUCT" }, "alert_id": { "type": "string", "description": "The unique identifier for this alert in the Rapid7 product.", "example": "620ba5123b2aff3303ed65f3" }, "type": { "type": "string", "description": "The type classification of the alert.", "example": "Phishing" }, "title": { "type": "string", "description": "The title of the alert.", "example": "Suspicious login attempt detected." }, "sub_type": { "type": "string", "description": "The sub-type classification of the alert.", "example": "credential_theft" }, "severity": { "type": "string", "description": "The severity level of the alert.", "example": "High" }, "description": { "type": "string", "description": "A description of the alert.", "example": "A suspicious login attempt was detected from an unknown IP address." }, "url": { "type": "string", "description": "A deep link URL to the alert in the originating product.", "example": "https://example.com/alerts/620ba5123b2aff3303ed65f3" }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional key-value attributes associated with the alert.", "example": { "source_ip": "192.0.2.1", "destination_ip": "198.51.100.5" } } }, "required": [ "alert_id", "product" ] }, "InsightAgentInfoDto": { "type": "object", "properties": { "alert_id": { "type": "string", "description": "The unique identifier for this alert in the Insight Agent.", "example": "01212121-0000-1111-92b0-67ed112073b8" }, "alert_type": { "type": "string", "description": "The type of alert in the Insight Agent.", "example": "Endpoint Prevention" }, "agent_action_taken": { "type": "string", "description": "The action that was taken by the Insight Agent, as mentioned in this alert.", "example": "Block" } }, "required": [ "alert_id", "alert_type" ] }, "SecondPartyInfoDtoV2": { "type": "object", "properties": { "type": { "type": "string", "description": "String representing the Rapid7 product which is associated with the investigation.", "example": "THREAT_COMMAND" }, "threat_command_details": { "$ref": "#/components/schemas/ThreatCommandInfoDto", "description": "Object representing the Threat Command alert associated with an investigation. This object will be present only when the Type field is set to 'THREAT_COMMAND'.", "example": { "alert_id": "620ba5123b2aff3303ed65f3", "alert_type": "Phishing", "applicable_close_reasons": [ "ProblemSolved", "InformationalOnly", "Other" ] } }, "insight_agent_details": { "type": "array", "description": "Object representing the Insight Agent alert associated with an investigation. This object will be present only when the Type field is set to 'INSIGHT AGENT'.", "example": [ { "alert_id": "972bef1b-72c9-48d2-9e33-ca9056cfe086", "alert_type": "Endpoint Prevention", "agent_action_taken": "Block" } ], "items": { "$ref": "#/components/schemas/InsightAgentInfoDto" } }, "rapid7_product_info": { "$ref": "#/components/schemas/GenericSecondPartyInfoDto", "description": "A product-agnostic representation of the Rapid7 product alert. This object provides baseline alert information regardless of product type.", "example": { "product": "EXAMPLE_PRODUCT", "alert_id": "620ba5123b2aff3303ed65f3", "title": "Suspicious login attempt detected.", "description": "A suspicious login attempt was detected from an unknown IP address.", "type": "Phishing", "sub_type": "credential_theft", "severity": "High", "url": "https://example.com/alerts/620ba5123b2aff3303ed65f3", "attributes": { "source_ip": "192.0.2.1" } } } }, "required": [ "type" ] }, "ThreatCommandInfoDto": { "type": "object", "properties": { "alert_id": { "type": "string", "description": "The unique identifier for this alert in Threat Command.", "example": "620ba5123b2aff3303ed65f3" }, "alert_type": { "type": "string", "description": "The type of alert in Threat Command.", "example": "Phishing" }, "applicable_close_reasons": { "type": "array", "description": "The list of applicable close reasons, based on the alert type, that can be used to close an alert on Threat Command side.", "example": [ "ProblemSolved", "InformationalOnly", "Other" ], "items": { "type": "string" } } }, "required": [ "alert_id", "alert_type", "applicable_close_reasons" ] }, "DetectionRuleDto": { "type": "object", "properties": { "ruleName": { "type": "string", "description": "The name of the detection rule.", "example": "Attacker Technique - Accessibility Tool Launching Process" }, "ruleRrn": { "$ref": "#/components/schemas/RRN", "description": "The rrn of the detection rule.", "example": "rrn:cba:::detection-rule:FX11KBBSCK20" } }, "required": [ "ruleName", "ruleRrn" ] }, "InvestigationAlertDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The alert's ID.", "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, "title": { "type": "string", "description": "The alert's title", "example": "Account jdoe had INBOUND firewall traffic from 1.2.3.4 (tracked in MyThreat) to 10.1.2.3" }, "alertType": { "type": "string", "description": "The alert's type.", "example": "Account Created" }, "alertTypeDescription": { "type": "string", "description": "A description of this type of alert.", "example": "A new account has been created." }, "createdTime": { "type": "string", "description": "The time the alert was created.", "example": "2018-06-06T16:56:42Z" }, "firstEventTime": { "type": "string", "description": "The time the first event involved in this alert occurred.", "example": "2018-06-06T16:56:42Z" }, "latestEventTime": { "type": "string", "description": "The time the most recent event involved in this alert occurred.", "example": "2018-06-06T16:56:42Z" }, "alertSource": { "type": "string", "description": "The source of the alert.", "example": "User Behavior Analytics" }, "detectionRuleRrn": { "$ref": "#/components/schemas/DetectionRuleDto", "description": "The detection rule that generated this alert, if any." } }, "required": [ "alertSource", "alertType", "alertTypeDescription", "createdTime", "id", "title" ] }, "PageInvestigationAlertDto": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of data that matches the pagination parameters. If no results match, this will be an empty list.", "items": { "$ref": "#/components/schemas/InvestigationAlertDto" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata", "description": "The pagination parameters used to generate this page result. " } }, "required": [ "data", "metadata" ] }, "HealthMetricsErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "A human-readable message describing the error that occurred.", "example": "A human-readable message describing the error that occurred." }, "correlation_id": { "type": "string", "description": "An identifier that uniquely identifies the failed request.", "example": "6b6503c8-2da9-41c0-94cb-2f34069e00cd" } }, "required": [ "message" ] }, "AgentSummaryHealthV2": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "offline": { "type": "integer", "format": "int64", "description": "Number of offline agents", "example": 5 }, "online": { "type": "integer", "format": "int64", "description": "Number of online agents", "example": 25 }, "stale": { "type": "integer", "format": "int64", "description": "Number of stale agents", "example": 3 }, "total": { "type": "integer", "format": "int64", "description": "Total number of agents", "example": 33 } } }, "CollectorsHealthV2": { "type": "object", "properties": { "id": { "type": "string", "description": "Collector identifier", "example": "collector-001" }, "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": "string", "description": "Collector name", "example": "Main Collector" }, "state": { "type": "string", "description": "Current collector state", "example": "RUNNING" }, "last_active": { "type": "string", "format": "date-time", "description": "Last time the collector was active", "example": "2025-09-18T10:30:00Z" }, "event_sources_used": { "type": "integer", "format": "int64", "description": "Number of event sources currently in use", "example": 15 }, "max_event_sources": { "type": "integer", "format": "int64", "description": "Maximum number of event sources allowed", "example": 100 }, "issue": { "$ref": "#/components/schemas/Issue", "description": "Current issue with the collector, if any" }, "memory_used": { "type": [ "integer", "null" ], "format": "int64", "description": "Memory currently used by the collector in MB", "example": 2048 }, "max_memory": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum memory available to the collector in MB", "example": 4096 }, "percent_cpu_used": { "type": [ "number", "null" ], "format": "double", "description": "CPU utilization percentage", "example": 25.5 }, "hostname": { "type": [ "string", "null" ], "description": "Hostname of the collector, if known", "example": "example.rapid7.com" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the collector, if known", "example": "192.0.2.0" } } }, "DataExportersHealthV2": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": "string", "description": "Data exporter name", "example": "Main Data Exporter" }, "state": { "type": "string", "description": "Current data exporter state", "example": "RUNNING" }, "issue": { "$ref": "#/components/schemas/Issue", "description": "Current issue with the data exporter, if any" }, "last_active": { "type": [ "string", "null" ], "format": "date-time", "description": "Last time the data exporter was active", "example": "2025-09-18T10:30:00Z" } } }, "EventSourcesHealthV2": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": "string", "description": "Event source name", "example": "Main Event Source" }, "state": { "type": "string", "description": "Current event source state", "example": "ACTIVE" }, "last_active": { "type": "string", "format": "date-time", "description": "Last time the event source was active", "example": "2025-09-18T10:30:00Z" }, "issue": { "$ref": "#/components/schemas/Issue", "description": "Current issue with the event source, if any" }, "events_per_minute": { "type": [ "number", "null" ], "format": "double", "description": "Events per minute (EPM) for the event source. Present only when withEpm=true and EPM is available.", "example": 100 } } }, "HealthMetricsV2": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AgentSummaryHealthV2" }, { "$ref": "#/components/schemas/CollectorsHealthV2" }, { "$ref": "#/components/schemas/DataExportersHealthV2" }, { "$ref": "#/components/schemas/EventSourcesHealthV2" }, { "$ref": "#/components/schemas/HoneypotsHealthV2" }, { "$ref": "#/components/schemas/OrchestratorHealthV2" }, { "$ref": "#/components/schemas/ScanEnginesHealthV2" }, { "$ref": "#/components/schemas/SensorsHealthV2" } ], "description": "Health metrics for various resource types", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" } } }, "HoneypotsHealthV2": { "type": "object", "properties": { "id": { "type": "string", "description": "Honeypot identifier", "example": "honeypot-001" }, "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": "string", "description": "Honeypot name", "example": "Main Honeypot" }, "state": { "type": "string", "description": "Current honeypot state", "example": "ACTIVE" }, "last_active": { "type": "string", "format": "date-time", "description": "Last time the honeypot was active", "example": "2025-09-18T10:30:00Z" }, "issue": { "$ref": "#/components/schemas/Issue", "description": "Current issue with the honeypot, if any" }, "memory_used": { "type": [ "integer", "null" ], "format": "int64", "description": "Memory currently used by the honeypot in MB", "example": 512 }, "max_memory": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum memory available to the honeypot in MB", "example": 1024 }, "percent_cpu_used": { "type": [ "number", "null" ], "format": "double", "description": "CPU utilization percentage", "example": 10.5 } } }, "Issue": { "type": "null", "properties": { "severity": { "type": "string" }, "message": { "type": "string" }, "event_time": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrchestratorHealthV2": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": "string", "description": "Orchestrator name", "example": "Main Orchestrator" }, "state": { "type": "string", "description": "Current orchestrator state", "example": "RUNNING" }, "last_active": { "type": "string", "description": "Last time the orchestrator was active", "example": "2025-09-18T10:30:00Z" }, "cpu_used": { "type": "number", "format": "double", "description": "CPU utilization percentage", "example": 35.8 }, "memory_used": { "type": "integer", "format": "int64", "description": "Memory currently used by the orchestrator in MB", "example": 3072 }, "max_memory": { "type": "integer", "format": "int64", "description": "Maximum memory available to the orchestrator in MB", "example": 6144 }, "storage_used": { "type": "integer", "format": "int64", "description": "Storage currently used by the orchestrator in bytes", "example": 20971520 }, "max_storage": { "type": "integer", "format": "int64", "description": "Maximum storage available to the orchestrator in bytes", "example": 52428800 }, "hostname": { "type": [ "string", "null" ], "description": "Hostname of the orchestrator, if known", "example": "example.rapid7.com" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the orchestrator, if known", "example": "192.0.2.0" } } }, "PageHealthMetricsV2": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of data that matches the pagination parameters. If no results match this will be an empty list.", "items": { "$ref": "#/components/schemas/HealthMetricsV2" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata", "description": "The pagination parameters used to generate this page result. Depending on the API, additional parameters may be dynamically present." } }, "required": [ "data", "metadata" ] }, "ScanEnginesHealthV2": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": [ "string", "null" ], "description": "Scan engine name", "example": "Main Scan Engine" }, "state": { "type": "string", "description": "Current scan engine state", "example": "RUNNING" }, "storage_used": { "type": "integer", "format": "int64", "description": "Storage currently used by the scan engine in bytes", "example": 52428800 }, "max_storage": { "type": "integer", "format": "int64", "description": "Maximum storage available to the scan engine in bytes", "example": 104857600 }, "last_active": { "type": "string", "description": "Last time the scan engine was active", "example": "2025-09-18T10:30:00Z" }, "memory_used": { "type": "integer", "format": "int64", "description": "Memory currently used by the scan engine in MB", "example": 4096 }, "max_memory": { "type": "integer", "format": "int64", "description": "Maximum memory available to the scan engine in MB", "example": 8192 }, "percent_cpu_used": { "type": "number", "format": "float", "description": "CPU utilization percentage", "example": 45.2 } } }, "SensorsHealthV2": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Resource name for the health metric", "example": "rrn:rapid7:us:customer:12345:agent:678" }, "name": { "type": [ "string", "null" ], "description": "Sensor name", "example": "Main Sensor" }, "state": { "type": "string", "description": "Current sensor state", "example": "ACTIVE" }, "health_status": { "type": "array", "description": "List of health status indicators", "example": [ "OK", "MONITORING" ], "items": { "type": "string" } }, "storage_used": { "type": "integer", "format": "int64", "description": "Storage currently used by the sensor in bytes", "example": 15728640 }, "max_storage": { "type": "integer", "format": "int64", "description": "Maximum storage available to the sensor in bytes", "example": 104857600 }, "last_active": { "type": "string", "format": "date-time", "description": "Last time the sensor was active", "example": "2025-09-18T10:30:00Z" }, "memory_used": { "type": "integer", "format": "int64", "description": "Memory currently used by the sensor in MB", "example": 1024 }, "max_memory": { "type": "integer", "format": "int64", "description": "Maximum memory available to the sensor in MB", "example": 2048 }, "percent_cpu_used": { "type": "number", "format": "float", "description": "CPU utilization percentage", "example": 15.2 }, "drop_rate": { "type": [ "number", "null" ], "format": "float", "description": "Data drop rate as a percentage", "example": 0.01 }, "issue": { "$ref": "#/components/schemas/Issue", "description": "Current issue with the sensor, if any" } } } } } }