find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/rapid7-investigations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: InsightIDR Investigations API
  version: v1
  description: 'Introduction


    Welcome to the reference documentation for the InsightIDR public APIs.


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


    Learn about basic concepts and capabilities


    Get an Insight platform API key to set up authentication


    See available Insight product APIs


    Learn more about InsightIDR


    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
security: []
tags:
- name: Investigations
paths:
  /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'
components:
  schemas:
    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
    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
    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
    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
    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
    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
    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
externalDocs:
  description: Product docs
  url: https://insightidr.help.rapid7.com/docs