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-comments-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 Comments 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: 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.
paths:
  /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'
components:
  schemas:
    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
    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
    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
    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
    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
    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
    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
    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
externalDocs:
  description: Product docs
  url: https://insightidr.help.rapid7.com/docs