{ "openapi": "3.0.3", "info": { "title": "InsightIDR API", "version": "v1", "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://{region}.api.insight.rapid7.com/", "variables": { "region": { "default": "us", "description": "Insight API region" } } } ], "externalDocs": { "description": "Product docs", "url": "https://insightidr.help.rapid7.com/docs" }, "security": [], "tags": [ { "name": "Accounts", "description": "An API used to find and search InsightIDR accounts. See https://docs.rapid7.com/insightidr/users-and-accounts-on-your-domain for further information on accounts." }, { "name": "Local Accounts", "description": "An API used to find and search InsightIDR local accounts. See https://docs.rapid7.com/insightidr/users-and-accounts-on-your-domain for further information on local accounts." }, { "name": "Assets", "description": "An API used to find and search InsightIDR assets. See https://docs.rapid7.com/insightidr/assets-on-your-domain for further information on assets." }, { "name": "Attachments", "description": "An API used to upload, list, download and delete attachments. For example, the create API can be used to upload an attachment." }, { "name": "Comments", "description": "An API used to find, create, and delete comments. For example, these APIs can be used to create a comment for a particular investigation." }, { "name": "Community Threats", "description": "An API used to add and replace indicators for Community Threats. See https://insightidr.help.rapid7.com/docs/threats#section-threat-api for further information on how to generate threat keys." }, { "name": "Users", "description": "An API used to find and search InsightIDR users. See https://docs.rapid7.com/insightidr/users-and-accounts-on-your-domain for further information on users." }, { "name": "Health Metrics", "description": "An API used to retrieve health metrics of an organization." }, { "name": "Collectors", "description": "An API used to manage collectors for an organization." } ], "paths": { "/idr/v1/accounts/_search": { "post": { "tags": [ "Accounts" ], "summary": "Search accounts", "description": "A search API for accounts. You can search for accounts matching the given search criteria.
FieldCan Search?Can Sort?Type
authentication_serviceYesYesString
disabledYesNoBoolean
domainYesYesString
nameYesYesString
user.rrnYesYesString
user.nameYesYesString
", "operationId": "searchAccounts", "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": { "minimum": 0, "type": "integer", "default": 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 1000.", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 20 }, "example": 20 } ], "requestBody": { "description": "The criteria and sorting information for searching.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAccountV2" } } } }, "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/v1/accounts/{rrn}": { "get": { "tags": [ "Accounts" ], "summary": "Get account by RRN", "description": "Retrieve an account with the given RRN (Rapid7 Resource Name).", "operationId": "findAccountByRrn", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the account.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountV2" } } } }, "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/v1/assets/local-accounts/_search": { "post": { "tags": [ "Local Accounts" ], "summary": "Search local accounts", "description": "A search API for local accounts. You can search for local accounts matching the given search criteria.
FieldCan Search?Can Sort?Type
nameYesYesString
asset.rrnYesYesString
asset.nameYesYesString
user.rrnYesYesString
user.nameYesYesString
", "operationId": "searchLocalAccounts", "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": { "minimum": 0, "type": "integer", "default": 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 1000.", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 20 }, "example": 20 } ], "requestBody": { "description": "The criteria and sorting information for searching.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageLocalAccountV2" } } } }, "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/v1/assets/_search": { "post": { "tags": [ "Assets" ], "summary": "Search assets", "description": "A search API for assets. You can search for assets matching the given search criteria.
FieldCan Search?Can Sort?Type
nameYesYesString
", "operationId": "searchAssets", "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": { "minimum": 0, "type": "integer", "default": 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 1000.", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 20 }, "example": 20 } ], "requestBody": { "description": "The criteria and sorting information for searching.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAssetV2" } } } }, "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/v1/assets/{rrn}": { "get": { "tags": [ "Assets" ], "summary": "Get asset by RRN", "description": "Retrieve an asset with the given RRN (Rapid7 Resource Name).", "operationId": "findAssetByRrn", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the asset.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetV2" } } } }, "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/v1/assets/local-accounts/{rrn}": { "get": { "tags": [ "Local Accounts" ], "summary": "Get local account by RRN", "description": "Retrieve a local account with the given RRN (Rapid7 Resource Name).", "operationId": "getLocalAccountByRrn", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the local account.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalAccountV2" } } } }, "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/v1/attachments": { "get": { "tags": [ "Attachments" ], "summary": "List attachments", "description": "Retrieves attachments matching the given request parameters. For example, this API allows you to list all attachments by investigation.", "operationId": "listAttachments", "parameters": [ { "name": "target", "in": "query", "description": "Return attachments with this target.", "required": true, "schema": { "type": "string" }, "example": "rrn:investigation:us:01234567-89ab-cdef-0000-123123123123:investigation:ABCDEF543210" }, { "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 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAttachment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } } }, "post": { "tags": [ "Attachments" ], "summary": "Upload attachment", "description": "An API used to upload one or more attachments. By default, attachments are not associated with a comment. Use this API to create comment.", "operationId": "uploadAttachment", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/UploadAttachmentRequest" } }, "application/json": { "schema": { "type": "object", "properties": { "filedata": { "type": "array", "items": { "type": "string", "format": "binary" } } }, "required": [ "filedata" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } } } }, "/idr/v1/attachments/{rrn}": { "get": { "tags": [ "Attachments" ], "summary": "Download attachment", "description": "An API you can use to download an attachment by RRN. The RRN determines which attachment is downloaded.", "operationId": "downloadAttachment", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the attachment.", "required": true, "schema": { "type": "string" }, "example": "rrn:collaboration:us:01234567-89ab-cdef-0000-123123123123:attachment:ABCDEF543210" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "403": { "description": "Insufficient Permissions", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Entity Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "405": { "description": "Method Not Allowed", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "502": { "description": "Bad Gateway", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "503": { "description": "Service Unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "504": { "description": "Gateway Timeout", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } } }, "delete": { "tags": [ "Attachments" ], "summary": "Delete an attachment", "description": "An API you can use to delete an attachment with the given RRN.", "operationId": "deleteAttachment", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the attachment.", "required": true, "schema": { "type": "string" }, "example": "rrn:collaboration:us:01234567-89ab-cdef-0000-123123123123:attachment:ABCDEF543210" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } } } }, "/idr/v1/attachments/{rrn}/metadata": { "get": { "tags": [ "Attachments" ], "summary": "Get attachment information", "description": "An API you can use to get information from an attachment by RRN. The RRN identifies the attachment.", "operationId": "getAttachment", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the attachment.", "required": true, "schema": { "type": "string" }, "example": "rrn:collaboration:us:01234567-89ab-cdef-0000-123123123123:attachment:ABCDEF543210" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse1" } } } } } } }, "/idr/v1/comments/{rrn}/{visibility}": { "put": { "tags": [ "Comments" ], "summary": "Update comment visibility", "description": "An API to update visibility of a comment by using an RRN. This API returns the comment with the updated visibility .", "operationId": "updateComment", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the comment.", "required": true, "schema": { "type": "string" }, "example": "rrn:collaboration:us:01234567-89ab-cdef-0000-123123123123:comment:ABCDEF543210" }, { "name": "visibility", "in": "path", "description": "The new visibility for the comment (case insensitive).", "required": true, "schema": { "type": "string", "enum": [ "INTERNAL", "PUBLIC" ], "example": "INTERNAL" } } ], "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } } } } }, "/idr/v1/comments": { "get": { "tags": [ "Comments" ], "summary": "List comments", "description": "Retrieves a page of comments matching the given request parameters. For example, this API allows you to list all comments on an investigation by passing an investigation's RRN as the target value.", "operationId": "listComments", "parameters": [ { "name": "target", "in": "query", "description": "Return comments with this target.", "required": true, "schema": { "type": "string" }, "example": "rrn:investigation:us:01234567-89ab-cdef-0000-123123123123:investigation:ABCDEF543210" }, { "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 or equal to 100.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageComment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } } } }, "post": { "tags": [ "Comments" ], "summary": "Create comment", "description": "An API you can use to create comments for a particular target. The target determines where the comment will appear within InsightIDR. Only certain types of RRNs are permitted as targets, such as investigation RRNs.", "operationId": "createComment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } } } } }, "/idr/v1/comments/{rrn}": { "get": { "tags": [ "Comments" ], "summary": "Get comment by rrn", "description": "Retrieves a comment by its rrn.", "operationId": "getComment", "parameters": [ { "name": "rrn", "in": "path", "description": "Return a comment with this rrn.", "required": true, "schema": { "type": "string" }, "example": "rrn:collaboration:us:01234567-89ab-cdef-0000-123123123123:comment:ABCDEF543210" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } } } }, "delete": { "tags": [ "Comments" ], "summary": "Delete a comment", "description": "A delete API you can use to delete a comment by using an RRN. The RRN determines which comment will be deleted. Only the creator of a comment can delete it.", "operationId": "deleteComment", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the comment.", "required": true, "schema": { "type": "string" }, "example": "rrn:collaboration:us:01234567-89ab-cdef-0000-123123123123:comment:ABCDEF543210" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "401": { "description": "Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "403": { "description": "Insufficient Permissions", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "404": { "description": "Entity Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "405": { "description": "Method Not Allowed", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "500": { "description": "Internal Server Error", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "502": { "description": "Bad Gateway", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "503": { "description": "Service Unavailable", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } }, "504": { "description": "Gateway Timeout", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorResponse2" } } } } } } }, "/idr/v1/customthreats": { "post": { "tags": [ "Community Threats" ], "summary": "Create a Community Threat", "description": "Create a private InsightIDR Community Threat and add indicators to this Community Threat. The following Community Threat indicators are supported in the request body, formatted as JSON:The request content type must be to in JSON (see request samples).
The maximum file size is 50 MB.", "operationId": "createCommunityThreat", "requestBody": { "description": "The request body format must be in JSON. \nThe maximum payload size is 50 MB.", "content": { "application/json": { "schema": { "type": "string" }, "example": { "threat": "threatName", "note": "notetext", "indicators": { "ips": [ "192.168.0.1" ], "hashes": [ "b95663ec7339033cf1fde459a34b6606" ], "domain_names": [ "rapid7.com", "mailxpy.com" ], "urls": [ "http://example.com/index", " http://www.mailxpy.com/login/index.php" ] } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreatUpdateResult" } } } }, "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" } } } }, "413": { "description": "Payload Is Too Large", "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/v1/customthreats/key/{key}/indicators/replace": { "post": { "tags": [ "Community Threats" ], "summary": "Replace indicators for a Community Threat", "description": "Replace InsightIDR Community Threat indicators for a Community Threat with the given Community Threat key. The following Community Threat indicators are supported in the request body formatted as JSON, STIX XML, or CSV:
The request content type is expected to match the specified format: \"application/json\" for \"json\" format, \"text/xml\" for \"stix_xml\" format and \"text/csv\" for \"csv\" format. See request samples on the right.
The multipart file upload (with multipart/form-data content type) is also supported by the endpoint. The maximum file size is 50 MB.", "operationId": "replaceIndicators", "parameters": [ { "name": "key", "in": "path", "description": "The key of a Community Threat for which the indicators are going to be added.", "required": true, "schema": { "type": "string" }, "example": "156c9e48-64da-4bba-939e-e1c329be591b" }, { "name": "format", "in": "query", "description": "The input format.", "required": true, "schema": { "type": "string", "enum": [ "json", "csv", "stix_xml" ] }, "example": "json" } ], "requestBody": { "description": "The request body format should be one of JSON, STIX XML, CSV, or multi-part file data. \nThe maximum payload size is 50 MB.", "content": { "application/json": { "schema": { "type": "string" }, "example": { "ips": [ "192.168.0.1" ], "hashes": [ "b95663ec7339033cf1fde459a34b6606" ], "domain_names": [ "rapid7.com" ], "urls": [ "http://example.com" ] } }, "text/csv": { "schema": { "type": "string" }, "example": "192.168.0.1,b95663ec7339033cf1fde459a34b6606,rapid7.com,http://example.com" }, "text/xml": { "schema": { "type": "string" }, "example": "\n\n \n Example watchlist that contains domain information.\n Indicators - Watchlist\n \n \n \n Domain Watchlist\n Sample domain Indicator for this watchlist\n \n \n \n malicious1.example.com##comma##malicious2.example.com##comma##malicious3.example.com\n \n \n \n \n \n \n 185.134.98.141\n \n \n \n \n \n" } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreatUpdateResult" } } } }, "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" } } } }, "413": { "description": "Payload Is Too Large", "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/v1/customthreats/key/{key}/indicators/add": { "post": { "tags": [ "Community Threats" ], "summary": "Add indicators to a Community Threat", "description": "Add InsightIDR Community Threat indicators to a Community Threat with the given Community Threat key. The following Community Threat indicators are supported in the request body formatted as JSON, STIX XML, or CSV:
The request content type is expected to match the specified format: \"application/json\" for \"json\" format, \"text/xml\" for \"stix_xml\" format and \"text/csv\" for \"csv\" format. See request samples on the right.
The multipart file upload (with multipart/form-data content type) is also supported by the endpoint. The maximum file size is 50 MB.", "operationId": "addIndicators", "parameters": [ { "name": "key", "in": "path", "description": "The key of a Community Threat for which the indicators are going to be added.", "required": true, "schema": { "type": "string" }, "example": "156c9e48-64da-4bba-939e-e1c329be591b" }, { "name": "format", "in": "query", "description": "The input format.", "required": true, "schema": { "type": "string", "enum": [ "json", "csv", "stix_xml" ] }, "example": "json" } ], "requestBody": { "description": "The request body format should be one of JSON, STIX XML, CSV, or multi-part file data. \nThe maximum payload size is 50 MB.", "content": { "application/json": { "schema": { "type": "string" }, "example": { "ips": [ "192.168.0.1" ], "hashes": [ "b95663ec7339033cf1fde459a34b6606" ], "domain_names": [ "rapid7.com" ], "urls": [ "http://example.com" ] } }, "text/csv": { "schema": { "type": "string" }, "example": "192.168.0.1,b95663ec7339033cf1fde459a34b6606,rapid7.com,http://example.com" }, "text/xml": { "schema": { "type": "string" }, "example": "\n\n \n Example watchlist that contains domain information.\n Indicators - Watchlist\n \n \n \n Domain Watchlist\n Sample domain Indicator for this watchlist\n \n \n \n malicious1.example.com##comma##malicious2.example.com##comma##malicious3.example.com\n \n \n \n \n \n \n 185.134.98.141\n \n \n \n \n \n" } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreatUpdateResult" } } } }, "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" } } } }, "413": { "description": "Payload Is Too Large", "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/v1/customthreats/key/{key}/delete": { "post": { "tags": [ "Community Threats" ], "summary": "Delete a Community Threat", "description": "Delete an owned InsightIDR Community Threat.", "operationId": "deleteCommunityThreat", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteThreatEvent" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Threat" } } } }, "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": "Threat with key threatKey was 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/v1/investigations/{id}/status/{status}": { "put": { "tags": [ "Investigations" ], "summary": "Set the status of an investigation", "description": "An API that sets the status of the investigation with the given 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 change the status of.", "required": true, "schema": { "type": "string" }, "examples": { "investigationId": { "description": "investigationId", "value": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, "rrn": { "description": "rrn", "value": "rrn:investigation:us1:a2c78570-5346-4d76-b57a-230da72c5e58:investigation:ABSJB123U3O9" } } }, { "name": "status", "in": "path", "description": "The new status for the investigation (case-insensitive).", "required": true, "schema": { "type": "string", "enum": [ "OPEN", "CLOSED", "INVESTIGATING" ], "example": "OPEN" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investigation" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } } } } }, "/idr/v1/investigations/{id}/assignee": { "put": { "tags": [ "Investigations" ], "summary": "Assign user to investigation", "description": "An API that assigns a user to the specified investigation. 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" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignUserToInvestigationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investigation" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } } } } }, "/idr/v1/investigations/bulk_close": { "post": { "tags": [ "Investigations" ], "summary": "Close investigations in bulk", "description": "An API to close all investigations that match the parameters provided in the request body. This API returns the number of investigations that were closed and a list of their IDs.", "operationId": "bulkCloseInvestigations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCloseInvestigationsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosedInvestigations" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } } } } }, "/idr/v1/investigations": { "get": { "tags": [ "Investigations" ], "summary": "List investigations", "description": "An API to list all investigations. This API retrieves a page of investigations matching the given request parameters. The investigations will always be sorted by investigation created_time in descending order.", "operationId": "listInvestigations", "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 then or equal to 1000.", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 1000, "minimum": 1 }, "example": 20 }, { "name": "statuses", "in": "query", "description": "An optional, comma-separated set of investigation statuses. Only investigations whose status matches one of the entries in the list will be returned. If this parameter, is omitted investigations with any status may be returned.", "required": false, "schema": { "type": "string" }, "example": "OPEN, CLOSED, INVESTIGATING" }, { "name": "start_time", "in": "query", "description": "An optional, ISO-formatted timestamp. Only investigations whose createTime is after this date will be returned by the API. If this parameter is omitted, investigations with any create_time may be returned.", "required": false, "schema": { "type": "string" }, "example": "2018-07-01T00:00:00Z" }, { "name": "end_time", "in": "query", "description": "An optional, ISO-formatted timestamp. Only investigations whose createTime is before this date will be returned by the API. If this parameter is omitted, investigations with any create_time may be returned.", "required": false, "schema": { "type": "string" }, "example": "2018-07-04T00:00:00Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageInvestigation" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "403": { "description": "Insufficient Permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } }, "504": { "description": "Gateway Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse3" } } } } } } }, "/idr/v1/users/_search": { "post": { "tags": [ "Users" ], "summary": "Search users", "description": "A search API for users. You can search for users matching the given search criteria.
FieldCan Search?Can Sort?Type
first_nameYesYesString
last_nameYesYesString
nameYesYesString
domainYesNoString
", "operationId": "searchUsers", "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": { "minimum": 0, "type": "integer", "default": 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 1000.", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "default": 20 }, "example": 20 } ], "requestBody": { "description": "The criteria and sorting information for searching.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageUserV2" } } } }, "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/v1/users/{rrn}": { "get": { "tags": [ "Users" ], "summary": "Get user by RRN", "description": "Retrieve a user with the given RRN (Rapid7 Resource Name).", "operationId": "getUserByRrn", "parameters": [ { "name": "rrn", "in": "path", "description": "The RRN of the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserV2" } } } }, "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/v1/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": "getMetrics", "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": { "minimum": 0, "type": "integer", "default": 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": { "maximum": 100, "minimum": 1, "type": "integer", "default": 20 }, "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" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" }, "examples": { "Agent": { "description": "Health metrics for agent resources", "value": { "data": [ { "type": "agent", "rrn": "rrn:rapid7:us:customer:12345:agent:678", "offline": 5, "online": 25, "stale": 3, "total": 33 } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Collectors": { "description": "Health metrics for collector resources", "value": { "data": [ { "type": "collectors", "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 } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Data Exporters": { "description": "Health metrics for data exporter resources", "value": { "data": [ { "type": "data_exporters", "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": 0, "total_pages": 20, "total_data": 0 } } }, "Event Sources": { "description": "Health metrics for event source resources", "value": { "data": [ { "type": "event_sources", "rrn": "rrn:rapid7:us:customer:12345:event_source:source001", "name": "Main Event Source", "state": "ACTIVE", "last_active": "2025-09-18T10:30:00Z" } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Honeypots": { "description": "Health metrics for honeypot resources", "value": { "data": [ { "type": "honeypots", "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": 0, "total_pages": 20, "total_data": 0 } } }, "Orchestrator": { "description": "Health metrics for orchestrator resource", "value": { "data": [ { "type": "orchestrator", "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 } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Scan Engines": { "description": "Health metrics for scan engine resources", "value": { "data": [ { "type": "scan_engines", "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": 0, "total_pages": 20, "total_data": 0 } } }, "Sensors": { "description": "Health metrics for sensor resources", "value": { "data": [ { "type": "sensors", "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": 0, "total_pages": 20, "total_data": 0 } } } } } } }, "207": { "description": "Multi-Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" }, "examples": { "Agent": { "description": "Health metrics for agent resources", "value": { "data": [ { "type": "agent", "rrn": "rrn:rapid7:us:customer:12345:agent:678", "offline": 5, "online": 25, "stale": 3, "total": 33 } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Collectors": { "description": "Health metrics for collector resources", "value": { "data": [ { "type": "collectors", "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 } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Data Exporters": { "description": "Health metrics for data exporter resources", "value": { "data": [ { "type": "data_exporters", "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": 0, "total_pages": 20, "total_data": 0 } } }, "Event Sources": { "description": "Health metrics for event source resources", "value": { "data": [ { "type": "event_sources", "rrn": "rrn:rapid7:us:customer:12345:event_source:source001", "name": "Main Event Source", "state": "ACTIVE", "last_active": "2025-09-18T10:30:00Z" } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Honeypots": { "description": "Health metrics for honeypot resources", "value": { "data": [ { "type": "honeypots", "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": 0, "total_pages": 20, "total_data": 0 } } }, "Orchestrator": { "description": "Health metrics for orchestrator resource", "value": { "data": [ { "type": "orchestrator", "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 } ], "metadata": { "index": 0, "size": 0, "total_pages": 20, "total_data": 0 } } }, "Scan Engines": { "description": "Health metrics for scan engine resources", "value": { "data": [ { "type": "scan_engines", "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": 0, "total_pages": 20, "total_data": 0 } } }, "Sensors": { "description": "Health metrics for sensor resources", "value": { "data": [ { "type": "sensors", "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": 0, "total_pages": 20, "total_data": 0 } } } } } } }, "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/v1/collectors": { "post": { "tags": [ "Collectors" ], "summary": "Add Collector", "description": "Add a new collector. The API key used must be associated with a user with the collection administration role.", "operationId": "addCollector", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCollectorRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCollectorResponse" } } } }, "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" } } } } } } } }, "components": { "schemas": { "ErrorResponse": { "required": [ "message" ], "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" } } }, "SearchRequest": { "type": "object", "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" } } } }, "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": { "type": "object", "description": "The value to search for." } }, "description": "The criteria for which entities to return." }, "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", "ASC,DESC" ] } }, "description": "The sorting information." }, "AccountV2": { "required": [ "authentication_service", "disabled", "name", "rrn", "user" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "The unique identifier for this account.", "example": "rrn:uba:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:account:83002c85d7c6" }, "name": { "type": "string", "description": "The name for this account.", "example": "jdoe@acme.com" }, "domain": { "type": "string", "description": "The domain that this account is associated with.", "example": "tor.acme.com" }, "disabled": { "type": "boolean", "description": "True if the account is disabled." }, "user": { "$ref": "#/components/schemas/UserSummaryV2" }, "authentication_service": { "type": "string", "description": "The service to which this account is tied, which is responsible for authenticating this account.", "example": "ACTIVE_DIRECTORY" } }, "description": "Information about an account" }, "PageAccountV2": { "required": [ "data", "metadata" ], "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/AccountV2" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata" } } }, "PageMetadata": { "required": [ "index", "size", "total_data", "total_pages" ], "type": "object", "properties": { "index": { "type": "integer", "description": "The 0 based index of the page retrieved. ", "format": "int32", "example": 0 }, "size": { "type": "integer", "description": "The size of the page requested. ", "format": "int32", "example": 20 }, "total_pages": { "type": "integer", "description": "The total number of pages available with the given filter parameters. ", "format": "int32", "example": 1 }, "total_data": { "type": "integer", "description": "The total number of results available with the given filter parameters. ", "format": "int64", "example": 15 } }, "description": "The pagination parameters used to generate this page result. Depending on the API, additional parameters may be dynamically present." }, "UserSummaryV2": { "required": [ "name", "rrn" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "The unique identifier for this user.", "example": "rrn:uba:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:user:83002c85d7c6" }, "name": { "type": "string", "description": "The name for this user.", "example": "John Doe" } }, "description": "The user this account is associated with." }, "AssetV2": { "required": [ "name", "rrn" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "The unique identifier for this asset.", "example": "rrn:uba:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:asset:83002c85d7c6" }, "name": { "type": "string", "description": "The user-friendly name for this asset.", "example": "morbo.tor.acme.com" } }, "description": "The asset this local account is associated with." }, "LocalAccountV2": { "required": [ "asset", "name", "rrn" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "The unique identifier for this local account.", "example": "rrn:uba:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:asset:account:83002c85d7c6" }, "name": { "type": "string", "description": "The name for this local account. ", "example": "jdoe" }, "user": { "$ref": "#/components/schemas/UserSummaryV21" }, "asset": { "$ref": "#/components/schemas/AssetV2" } }, "description": "The list of data that matches the pagination parameters. If no results match this will be an empty list." }, "PageLocalAccountV2": { "required": [ "data", "metadata" ], "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/LocalAccountV2" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata" } } }, "UserSummaryV21": { "required": [ "name", "rrn" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "The unique identifier for this user.", "example": "rrn:uba:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:user:83002c85d7c6" }, "name": { "type": "string", "description": "The name for this user.", "example": "John Doe" } }, "description": "The user this local account is associated with." }, "PageAssetV2": { "required": [ "data", "metadata" ], "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/AssetV2" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata" } } }, "ErrorResponse1": { "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." } }, "required": [ "message" ] }, "UploadAttachmentRequest": { "type": "object", "properties": { "filedata": { "type": "array", "description": "The list of files to upload as attachments.", "items": { "type": "string", "format": "binary" } } } }, "Attachment": { "type": "object", "properties": { "rrn": { "$ref": "#/components/schemas/RRN", "description": "The RRN of the attachment.", "example": "rrn:collaboration::orgId_123:attachment:d7812988-f171-4164-9309-65c32d5da28f" }, "creator": { "$ref": "#/components/schemas/Creator", "description": "Who or what created the resource." }, "created_time": { "type": "string", "description": "The time the attachment was created as an ISO formatted timestamp.", "example": "2018-06-06T16:56:42Z" }, "file_name": { "type": "string", "description": "The original filename of the uploaded attachment.", "example": "screenshot.png" }, "mime_type": { "type": "string", "description": "The mime type of the attachment.", "example": "image/png" }, "size": { "type": "integer", "format": "int64", "description": "The size in bytes of the attachment.", "example": 12345 }, "scan_status": { "type": "string", "description": "The scan status of the attachment, indicating whether the attachment has been scanned and, if so, the result. INFECTED or PENDING attachments may not be downloaded.", "example": "CLEAN" } }, "required": [ "created_time", "creator", "file_name", "mime_type", "rrn", "scan_status", "size" ] }, "Creator": { "type": "object", "properties": { "type": { "type": "string", "description": "A type that denotes who or what created a resource.", "enum": [ "USER", "ORG_API_KEY", "SYSTEM" ], "example": "USER" }, "name": { "type": "string", "description": "The name of who or what created a resource.", "example": "John Doe" } }, "required": [ "name", "type" ] }, "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" } } }, "PageAttachment": { "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/Attachment" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata1", "description": "The pagination parameters used to generate this page result." } }, "required": [ "data", "metadata" ] }, "PageMetadata1": { "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" ] }, "ErrorResponse2": { "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." } }, "required": [ "message" ] }, "CommentCreateRequest": { "type": "object", "description": "The information needed by the request body to create comments.", "properties": { "target": { "type": "string", "description": "The target of the comment, which determines where it will appear within InsightIDR.", "example": "rrn:investigation:us:01234567-89ab-cdef-0000-123123123123:investigation:ABCDEF543210" }, "body": { "type": "string", "description": "The body of the comment.", "example": "Here is my comment." }, "attachments": { "type": "array", "description": "An array of attachment RRNs to associate with the comment.", "example": [ "rrn:collaboration::orgId_123:attachment:d7812988-f171-4164-9309-65c32d5da28f" ], "items": { "type": "string" }, "uniqueItems": true } }, "required": [ "target" ] }, "Comment": { "type": "object", "properties": { "created_time": { "type": "string", "description": "The time the comment was created as an ISO formatted timestamp.", "example": "2018-06-06T16:56:42Z" }, "rrn": { "type": "string", "description": "The RRN of the comment.", "example": "rrn:investigation:us:01234567-89ab-cdef-0000-123123123123:comment:98765FEBCAD" }, "target": { "type": "string", "description": "The target where the comment belongs to.", "example": "rrn:investigation:us:01234567-89ab-cdef-0000-123123123123:investigation:ABCDEF543210" }, "creator": { "$ref": "#/components/schemas/Creator", "description": "Who or what created the resource." }, "body": { "type": "string", "description": "The body of the comment.", "example": "Here is my comment." }, "visibility": { "type": "string", "description": "Who can view the comment.", "example": "PUBLIC" }, "attachments": { "type": "array", "description": "List of attachments associated with this comment.", "items": { "$ref": "#/components/schemas/Attachment" } } }, "required": [ "body", "creator", "rrn", "target" ] }, "PageComment": { "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/Comment" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata2", "description": "The pagination parameters used to generate this page result." } }, "required": [ "data", "metadata" ] }, "PageMetadata2": { "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" ] }, "Threat": { "required": [ "indicator_count", "name", "published" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the threat.", "example": "Threat" }, "note": { "type": "string", "description": "Notes about this threat.", "example": "Notes" }, "published": { "type": "boolean", "description": "Indicates whether this threat has been published.", "example": true }, "indicator_count": { "minimum": 0, "type": "integer", "description": "The number of indicators in this threat.", "format": "int64", "example": 1 } }, "description": "The information about the threat." }, "ThreatUpdateResult": { "required": [ "threat" ], "type": "object", "properties": { "threat": { "$ref": "#/components/schemas/Threat" }, "rejected_indicators": { "type": "array", "description": "The list of indicators that have been rejected during the update.", "example": [ "blacklisted", "invalid" ], "items": { "type": "string" } } } }, "DeleteThreatEvent": { "type": "object", "properties": { "reason": { "type": "string" } } }, "ErrorResponse3": { "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." } }, "required": [ "message" ] }, "AlertInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "The alert's type.", "example": "Account Created" }, "type_description": { "type": "string", "description": "An optional description of this type of alert.", "example": "A new account has been created." }, "first_event_time": { "type": "string", "description": "The time the first event involved in this alert occurred.", "example": "2018-06-06T16:56:42Z" } }, "required": [ "type" ] }, "Assignee": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the assigned user.", "example": "Ellen Example" }, "email": { "type": "string", "description": "The email of the assigned user.", "example": "example@test.com" } }, "required": [ "email", "name" ] }, "Investigation": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the investigation.", "example": "174e4f99-2ac7-4481-9301-4d24c34baf06" }, "rrn": { "type": "string", "description": "The RRN of the investigation.", "example": "rrn:investigation:us1:174e4f99-2ac7-4481-9301-4d24c34baf06:investigation:6A74T2A4" }, "title": { "type": "string", "description": "The investigation's title.", "example": "Joe enabled account Joebob" }, "status": { "type": "string", "description": "The status of the investigations.", "enum": [ "OPEN,INVESTIGATING,CLOSED" ], "example": "OPEN" }, "source": { "type": "string", "description": "The source of this investigation.", "example": "ALERT" }, "disposition": { "type": "string", "description": "This disposition of this investigation.", "enum": [ "BENIGN,MALICIOUS,NOT_APPLICABLE,UNSPECIFIED" ], "example": "BENIGN" }, "assignee": { "$ref": "#/components/schemas/Assignee", "description": "The user assigned to this investigation, if any." }, "alerts": { "type": "array", "description": "The alerts involved in this investigation, if any.", "items": { "$ref": "#/components/schemas/AlertInfo" } }, "created_time": { "type": "string", "description": "The time the investigation was created, as an ISO formatted timestamp.", "example": "2018-06-06T16:56:42Z" } }, "required": [ "created_time", "id", "rrn", "source", "status", "title" ] }, "AssignUserToInvestigationRequest": { "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" ] }, "BulkCloseInvestigationsRequest": { "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 must be specified as well.", "enum": [ "ALERT,MANUAL,HUNT" ], "example": "ALERT" }, "alert_type": { "type": "string", "description": "The category of alerts that should be closed. This parameter is required if the source is ALERT and ignored for other sources. This value must exactly match the alert type returned by the List Investigations response.", "example": "Attacker Behavior Detected" }, "detection_rule_rrn": { "type": "string", "description": "The RRN of the detection rule. Investigations will only be closed that are associated with this detection rule. 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": "An ISO formatted timestamp. Only investigations whose createTime is after this date will be closed.", "example": "2018-07-01T00:00:00Z" }, "to": { "type": "string", "description": "An ISO formatted timestamp. Only investigations whose createTime is before this date will be closed.", "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 value is 0.", "example": 10 } }, "required": [ "from", "source", "to" ] }, "ClosedInvestigations": { "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" ] }, "PageInvestigation": { "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/Investigation" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata3", "description": "The pagination parameters used to generate this page result. " } }, "required": [ "data", "metadata" ] }, "PageMetadata3": { "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" ] }, "PageUserV2": { "required": [ "data", "metadata" ], "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/UserV2" } }, "metadata": { "$ref": "#/components/schemas/PageMetadata" } } }, "UserV2": { "required": [ "domain", "name", "rrn" ], "type": "object", "properties": { "rrn": { "type": "string", "description": "The unique identifier for this user.", "example": "rrn:uba:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:user:83002c85d7c6" }, "first_name": { "type": "string", "description": "The first name of this user, if known.", "example": "John" }, "last_name": { "type": "string", "description": "The last name of this user, if known.", "example": "Doe" }, "name": { "type": "string", "description": "The name of this user.", "example": "John Doe" }, "domain": { "type": "string", "description": "The domain this user is associated with.", "example": "tor.acme.com" } }, "description": "The list of data that matches the pagination parameters. If no results match this will be an empty list." }, "Page": { "required": [ "data", "metadata" ], "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": { "type": "object", "description": "The list of data that matches the pagination parameters. If no results match this will be an empty list." } }, "metadata": { "$ref": "#/components/schemas/PageMetadata" } } }, "AddCollectorRequest": { "required": [ "key", "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name for the new collector. Must be unique.", "example": "My Collector" }, "key": { "type": "string", "description": "The registration key for the collector. Must be unique, and a valid UUID.", "example": "ae1d4845-8ce8-4072-b4d5-77171387fb6a" }, "deployment_type": { "type": "string", "description": "Optional indication of how the collector is deployed.", "example": "kubernetes" } }, "description": "Request body for creating a collector" }, "AddCollectorResponse": { "required": [ "id", "name", "rrn" ], "type": "object", "properties": { "id": { "type": "string", "description": "The identifier for this collector.", "example": "ae1d4845-8ce8-4072-b4d5-77171387fb6a" }, "rrn": { "$ref": "#/components/schemas/RRN1" }, "name": { "type": "string", "description": "The name of this collector.", "example": "My Collector" } }, "description": "Response from creating a collector" }, "RRN1": { "type": "object", "properties": { "partition": { "type": "string" }, "service": { "type": "string" }, "regionCode": { "type": "string" }, "organizationId": { "type": "string" }, "resourceTypes": { "type": "array", "items": { "type": "string" } }, "resource": { "type": "string" } }, "description": "The unique identifier for this collector.", "example": "rrn:collection:us:6bcf6c5b-552d-49a4-a3f5-259e0514585f:collector:ae1d4845-8ce8-4072-b4d5-77171387fb6a" } } } }