Huntress Incident Reports API

openapi: 3.2.0
info:
  title: Huntress API Reference Incident Reports API
  description: '© Huntress - All rights reserved


    Introduction


    Webhook event payloads are available via the dropdown menu above the search bar on this page.'
  version: 1.0.0
servers:
- url: https://api.huntress.io
security:
- basic:
  - basic_auth
tags:
- name: Incident Reports
  description: Operations about Incident Reports
paths:
  /v1/incident_reports:
    get:
      summary: List Incident Reports
      description: 'Shows Incident Reports associated with your account.


        **Note:** This endpoint will also return a `pagination` key on the root level.

        Please refer to the pagination section within our docs for more information.'
      parameters:
      - in: query
        name: limit
        description: Max number of resources returned in a paged collection. Defaults to 10, with a minimum of 1 and maximum 500.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 500
          minimum: 1
      - in: query
        name: page_token
        description: Token used to request the next page in paginated results. Defaults to 'null'
        required: false
        schema:
          type: string
      - in: query
        name: sort_field
        description: Field to sort by. Defaults to 'id'.
        required: false
        schema:
          type: string
          enum:
          - id
          - created_at
          - updated_at
          default: id
      - in: query
        name: sort_direction
        description: Sort direction. Defaults to 'desc'.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - in: query
        name: indicator_type
        description: Filter by indicator type. One of footholds, monitored_files, ransomware_canaries, antivirus_detections, process_detections, managed_identity, mde_detections, siem_detections, favicon_detections, behavioral_detections, email_security_detections, app_control, ai_misuse
        required: false
        schema:
          type: string
          enum:
          - footholds
          - monitored_files
          - ransomware_canaries
          - antivirus_detections
          - process_detections
          - managed_identity
          - mde_detections
          - siem_detections
          - favicon_detections
          - behavioral_detections
          - email_security_detections
          - app_control
          - ai_misuse
      - in: query
        name: status
        description: Filter by status. One of sent, closed, dismissed, auto_remediating, deleting, partner_dismissed
        required: false
        schema:
          type: string
          enum:
          - sent
          - closed
          - dismissed
          - auto_remediating
          - deleting
          - partner_dismissed
      - in: query
        name: severity
        description: Filter by severity. One of low, high, critical
        required: false
        schema:
          type: string
          enum:
          - low
          - high
          - critical
      - in: query
        name: platform
        description: Filter by platform. One of windows, darwin, microsoft_365, google, linux, email_security, other
        required: false
        schema:
          type: string
          enum:
          - windows
          - darwin
          - microsoft_365
          - google
          - linux
          - email_security
          - other
      - in: query
        name: organization_id
        description: Filter by organization ID within Huntress account
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: agent_id
        description: Filter by agent ID within Huntress account
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: List Incident Reports
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_reports:
                    type: array
                    items:
                      $ref: '#/components/schemas/IncidentReport'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - incident_reports
                - pagination
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentReport'
      tags:
      - Incident Reports
      operationId: getV1IncidentReports
  /v1/incident_reports/{id}:
    get:
      summary: Get Incident Report
      description: Shows details on a single Incident Report associated with your account.
      parameters:
      - in: path
        name: id
        description: Incident Report ID within Huntress account
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get Incident Report
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_report:
                    $ref: '#/components/schemas/IncidentReport'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentReport'
      tags:
      - Incident Reports
      operationId: getV1IncidentReportsId
  /v1/incident_reports/{id}/resolution:
    post:
      summary: Create an Incident Report Resolution
      description: 'Use this endpoint to resolve a single Incident Report. All remediations belonging to the Incident Report must be approved first.


        While resolution updates the report status to resolved, assisted remediations may still be running in the background and manual remediations may still require completion by a user.


        This endpoint requires an API key with permissions to resolve incident reports. **Note that the default account API key is read-only, so you''ll need to create a user-based API key with the appropriate permissions to access this endpoint**.'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Create an Incident Report Resolution
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_report:
                    $ref: '#/components/schemas/IncidentReport'
        '403':
          description: There was an issue with your API credential or permissions.
        '409':
          description: Incident Report cannot be resolved. Confirm that all remediations are approved and report status is 'sent'.
        '422':
          description: Incident Report cannot be resolved unless report status is 'sent'.
      tags:
      - Incident Reports
      operationId: postV1IncidentReportsIdResolution
  /v1/incident_reports/{incident_report_id}/remediations:
    get:
      summary: List Remediations
      description: 'Shows details of Remediations belonging to a single Incident Report.


        **Note:** This endpoint will also return a `pagination` key on the root level.

        Please refer to the pagination section within our docs for more information.'
      parameters:
      - in: path
        name: incident_report_id
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: limit
        description: Max number of resources returned in a paged collection. Defaults to 10, with a minimum of 1 and maximum 500.
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 500
          minimum: 1
      - in: query
        name: page_token
        description: Token used to request the next page in paginated results. Defaults to 'null'
        required: false
        schema:
          type: string
      - in: query
        name: sort_field
        description: Field to sort by. Defaults to 'id'.
        required: false
        schema:
          type: string
          enum:
          - id
          - created_at
          - updated_at
          default: id
      - in: query
        name: sort_direction
        description: Sort direction. Defaults to 'desc'.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - in: query
        name: types[]
        description: 'Filter by type of remediation. Must be a comma-separated string containing the values: assisted, manual, containment'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - assisted
            - manual
            - containment
      - in: query
        name: statuses[]
        description: 'Filter by status of remediation. Must be a comma-separated string containing the values: unapproved, approved, completed, failed, cancelled'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - unapproved
            - approved
            - completed
            - failed
            - cancelled
      responses:
        '200':
          description: List Remediations
          content:
            application/json:
              schema:
                type: object
                properties:
                  remediations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Remediation'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - remediations
                - pagination
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Remediation'
      tags:
      - Incident Reports
      operationId: getV1IncidentReportsIncidentReportIdRemediations
  /v1/incident_reports/{incident_report_id}/remediations/{remediation_id}:
    get:
      summary: Get Remediation
      description: Shows details for a single Remediation belonging to a single Incident Report
      parameters:
      - in: path
        name: incident_report_id
        required: true
        schema:
          type: integer
          format: int32
      - in: path
        name: remediation_id
        description: Incident Report ID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get Remediation
          content:
            application/json:
              schema:
                type: object
                properties:
                  remediation:
                    $ref: '#/components/schemas/Remediation'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Remediation'
      tags:
      - Incident Reports
      operationId: getV1IncidentReportsIncidentReportIdRemediationsRemediationId
  /v1/incident_reports/{incident_report_id}/remediations/bulk_approval:
    post:
      summary: Bulk Approve Remediations
      description: 'Approve all unapproved remediations for an Incident Report. Approval immediately triggers the execution of assisted remediations.

        Manual remediations are not executed, and must be independently completed. Once all remediations are approved,

        the incident report becomes eligible for resolution.


        This endpoint requires an API key with permissions to write to remediations. **Note that the default account API key is read-only, so you''ll need to create a user-based API key with the appropriate permissions to access this endpoint**.'
      parameters:
      - in: path
        name: incident_report_id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Bulk Approve Remediations
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_report:
                    $ref: '#/components/schemas/IncidentReport'
        '403':
          description: There was an issue with your API credential or permissions.
        '409':
          description: Incident Report must have a status of 'sent'.
        '422':
          description: Unable to approve remediations
      tags:
      - Incident Reports
      operationId: postV1IncidentReportsIncidentReportIdRemediationsBulkApproval
  /v1/incident_reports/{incident_report_id}/remediations/bulk_rejection:
    post:
      summary: Bulk Reject Remediations
      description: 'Reject all unapproved remediations for an Incident Report. Rejecting the remediations will send the incident report back to the Huntress SOC.


        This endpoint requires an API key with permissions to write to remediations. **Note that the default account API key is read-only, so you''ll need to create a user-based API key with the appropriate permissions to access this endpoint**.'
      parameters:
      - in: path
        name: incident_report_id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Remediations rejected.
        '403':
          description: There was an issue with your API credential or permissions.
        '409':
          description: Incident Report must have a status of 'sent'.
        '422':
          description: Unable to reject remediations
      tags:
      - Incident Reports
      operationId: RemediationBulkRejectionParameters
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemediationBulkRejectionParameters'
        required: true
components:
  schemas:
    Pagination:
      type: object
      properties:
        next_page_url:
          type: string
        next_page_token:
          type: string
      description: Pagination model
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: A unique identifier for the user.
        email:
          type: string
          example: john.smith@example.com
          description: The user's email.
        name:
          type: string
          example: John Smith
          description: The user's name.
    IncidentReport:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: A unique identifier for an incident report.
        account_id:
          type: integer
          format: int64
          example: 5
          description: Unique identifier for the account this incident report is associated with.
        agent_id:
          type: integer
          format: int64
          example: 12
          description: Unique identifier for the agent this incident report is associated with.
        body:
          type: string
          example: <Content>
          description: Autogenerated content describing the details of the incident in question.
        closed_at:
          type: string
          format: date-time
          example: '2022-03-15T14:22:00Z'
          description: ISO-8601 formatted timestamp for when this incident report had its status set to `closed`. Null if non-applicable.
        indicator_counts:
          type: object
          example:
            footholds: 1
            monitored_files: 0
            process_detections: 0
            ransomware_canaries: 0
            antivirus_detections: 0
          description: Mapping of indicator types to number of incidences of that threat in the context of this incident report.
        indicator_types:
          type: array
          items:
            type: string
          example:
          - footholds
          description: Unique list of threat indicators that have been found in the context of this incident report.
        organization_id:
          type: integer
          format: int64
          example: 4
          description: Unique identifier for the organization this incident report is associated with.
        platform:
          type: string
          example: windows
          description: The platform of the host machine (`darwin`,`google`,`microsoft_365`,`linux`,`windows`, or `other`).
        remediations:
          type: object
          example:
            total_count: 1
            has_more: false
            items:
            - id: 1
              type: manual
              action: Delete File
              parameters:
              - name: path
                description: c:\windows\system32\tasks\malicious_task
              status: completed
              approved_at: '2025-06-26T18:57:03Z'
              approved_by:
                id: '123123'
                email: john.smith@example.com
                name: John smith
              completed_at: '2025-06-26T18:57:03Z'
          description: This represents an itemized list of the first 10 remediations for an incident report. If there are more than 10, use the remediations endpoint to retrieve information about them.
        sent_at:
          type: string
          format: date-time
          example: '2022-03-01T21:00:00Z'
          description: ISO-8601 formatted timestamp for when a Huntress SOC analyst has notified necessary parties regarding this incident report. Null if not sent.
        severity:
          type: string
          example: low
          description: The severity of the incident report. Can be one of `low`, `high`, `critical`.
        status:
          type: string
          example: closed
          description: Status of the incident report. Can be one of `sent`, `closed`, `dismissed`
        status_updated_at:
          type: string
          format: date-time
          example: '2022-03-15T14:22:00Z'
          description: ISO-8601 formatted timestamp for when the status of this incident report was last updated.
        subject:
          type: string
          example: LOW - Incident on laptop01 (Test)
          description: Autogenerated one-line description of the incident.
        summary:
          type: string
          example: Huntress detected a malicious scheduled task on this host. We recommend removing the file and scheduled task listed in the remediation steps below.
          description: Details of the incident report, as provided by a Huntress SOC analyst.
        updated_at:
          type: string
          format: date-time
          example: '2022-03-01T20:31:30Z'
          description: ISO-8601 formatted timestamp for when this incident report was last updated.
      description: IncidentReport model
    Remediation:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: A unique identifier for a remediation.
        type:
          type: string
          example: manual
          description: 'The type of the remediation. Can be one of: assisted, manual, containment'
        action:
          type: string
          example: Delete File
          description: Description of the remediation's required steps.
        parameters:
          type: array
          items:
            type: string
          example:
          - name: path
            description: c:\windows\system32\tasks\malicious_task
          description: Additional context on how the remediation will be performed.<br>For containment remediations, this will be a string showing the entity to which the remediation was applied.<br>For assisted remediations this will be an array of key value pairs representing all the parameters that are related to the remediation.<br>Manual remediations will have no information.
        status:
          type: string
          example: completed
          description: 'The status of the remediation. Can be one of: unapproved, approved, completed, failed, cancelled'
        approved_at:
          type: string
          format: date-time
          example: '2025-06-26T18:57:03Z'
          description: ISO-8601 formatted timestamp for when the remediation was approved.
        approved_by:
          $ref: '#/components/schemas/User'
          example:
            id: 123123
            name: John Smith
            email: john.smith@example.com
          description: The user that approved the remediation.
        completed_at:
          type: string
          format: date-time
          example: '2025-06-26T18:57:03Z'
          description: ISO-8601 formatted timestamp for when the remediation was completed.
      description: Remediation model
    RemediationBulkRejectionParameters:
      type: object
      properties:
        comment:
          type: string
          description: A description of why the remediations were rejected. This explanation helps Huntress SOC analysts fix the remediation plan and re-issue the incident report.
        useful:
          type: boolean
          description: Whether or not the remediation plan was useful.
        name:
          type: string
          description: Name of the user rejecting the remediations. Falls back to the user attached to the API key if not provided.
        phone_number:
          type: string
          description: Phone number to be contacted by the Huntress SOC. Falls back to the phone number of the user attached to the API key if not provided.
        email:
          type: string
          description: Email to be contacted by the Huntress SOC. Falls back to the email of the user attached to the API key if not provided.
      required:
      - comment
      - useful
      description: Bulk Reject Remediations Remediations
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic