Huntress Escalations API

openapi: 3.2.0
info:
  title: Huntress API Reference Escalations 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: Escalations
  description: Operations about Escalations
paths:
  /v1/escalations:
    get:
      summary: List Escalations
      description: 'Shows Escalations associated with your account.

        Additional details for a specific escalation can be obtained by using the **GET Escalation** endpoint.


        Escalations are used to notify Huntress account administrators that a situation requires their attention.

        Below are some common use cases:

        - Security Operation Centers (SOC) suspect that an application being flagged as malicious is a false positive, and we want to get your authorization to allow-list the application moving forward.

        - A potential threat flagged by Managed Defender requires additional information (file path details, etc.) in order for Huntress to provide actionable assisted remediation steps.

        - A login event occurred from an unexpected country or VPN, and Huntress would like partner feedback on whether that event should be expected or unauthorized.


        Though Escalations are not incident reports, they do have severities (low, high, critical) associated with them that dictate an expected response time.


        **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
          - severity
          - due_at
          - 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: status
        description: Filter by status.
        required: false
        schema:
          type: string
          enum:
          - open
          - overdue
          - resolved
      - in: query
        name: severity
        description: Filter by severity.
        required: false
        schema:
          type: string
          enum:
          - low
          - high
          - critical
      - in: query
        name: subtype
        description: Filter by subtype.
        required: false
        schema:
          type: string
      - in: query
        name: organization_id
        description: Filter by organization ID.
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: List Escalations
          content:
            application/json:
              schema:
                type: object
                properties:
                  escalations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Escalation'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - escalations
                - pagination
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Escalation'
      tags:
      - Escalations
      operationId: getV1Escalations
  /v1/escalations/{id}:
    get:
      summary: Get Escalation
      description: Shows details on a single Escalation associated with your account.
      parameters:
      - in: path
        name: id
        description: Escalation ID within Huntress Account
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get Escalation
          content:
            application/json:
              schema:
                type: object
                properties:
                  escalation:
                    $ref: '#/components/schemas/EscalationWithEntities'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Escalation'
      tags:
      - Escalations
      operationId: getV1EscalationsId
  /v1/escalations/{id}/resolution:
    post:
      summary: Create an Escalation Resolution
      description: 'Allows you to resolve an Escalation. Creating a resolution updates the Escalation''s status

        to resolved. This endpoint requires an API key with permissions to write to Escalations. **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**.

        The behavior of this endpoint varies by Escalation type so your request should be crafted based on the specific Escalation you are interacting with.


        #### Simple Resolution


        For most types of Escalations, a POST to the resolution endpoint with only the Escalation''s ID is sufficient. This action resolves the Escalation directly without requiring any additional parameters.


        #### Complex Resolution


        For Escalations that have many entities which all require action, a call to this endpoint will **bulk resolve all associated entities at once**. The determination provided will be **applied to every single entity attached to the Escalation.**

        Note that these kinds of Escalation resolutions require extra parameters in their requests.


        Escalation types that can resolve multiple associated entities at once are:

        - Unwanted Country Access

        - Unwanted VPN Access


        **NOTE:** Ommitting both `determination` and `scope` params will temporarily resolve the Unwanted Access Escalations.

        The escalation will reopen upon the next occurrence of the event that created the escalation.

        This is equivalent to using the "dismiss" option in the portal.'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '201':
          description: Create an Escalation Resolution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationResolution'
        '400':
          description: Invalid resolution parameters
        '403':
          description: There was an issue with your API credential or permissions.
        '409':
          description: Escalation has already been resolved
        '422':
          description: Escalation cannot be resolved through the API
      tags:
      - Escalations
      operationId: EscalationResolutionParameters
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EscalationResolutionParameters'
        required: true
components:
  schemas:
    EscalationResolution:
      type: object
      properties:
        escalation:
          $ref: '#/components/schemas/EscalationWithEntities'
          description: The resolved Escalation.
        resolution_method:
          type: string
          enum:
          - rule
          - dismiss
          - direct
          example: rule
          description: The code path the server took to resolve the Escalation. `rule` indicates a bulk resolution that created attribute rules from the supplied `determination` and `scope` parameters. `dismiss` indicates a temporary resolution from omitting both parameters on an Unwanted Access Escalation. `direct` indicates a simple resolution on an Escalation type that does not accept resolution parameters.
      required:
      - escalation
      - resolution_method
      description: EscalationResolution model
    EscalationResolutionParameters:
      type: object
      properties:
        determination:
          type: string
          description: Determination is only used for Unwanted Country Access and Unwanted VPN Access Escalations. This field determines whether **all** the associated identities are expected or unauthorized.
          enum:
          - expected
          - unauthorized
        scope:
          type: string
          description: 'Scope is used only for Unwanted Access Escalations. This determines what kinds of access rules are created in response to the Escalation. This parameter is better explained using an example:

            In the scenario when `email123@example.com` logs in from Russia and the determination is `unauthorized`:


            When the scope is `identity`:


            Rules created based on the resolution will only apply to the identities associated with the Escalation. In this case a rule will be created specifically preventing `email123@example.com` from logging in from Russia.


            When the scope is `organization`:


            Rules created based on the resolution will apply to all identities in the organization. In this case all logins from Russia will be prevented across the organization.


            When the scope is `account`:


            Rules created based on the resolution will apply to all identities on the account. In this case all logins from Russia will be prevented across the account.

            '
          enum:
          - account
          - organization
          - identity
      description: Create an Escalation Resolution
    EscalationWithEntities:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 84938
          description: A Huntress-unique identifier for the escalation.
        account:
          type: Account
          example:
            id: 1
            name: Your Account Name
          description: The Account the escalation pertains to.
        organizations:
          type: array
          items:
            type: string
          example:
          - id: 1234
            name: ExampleCo
          description: An array of Organizations this escalation pertains to
        created_at:
          type: string
          format: date-time
          example: '2025-09-05T18:20:34Z'
          description: ISO-8601 formatted timestamp for when this escalation was created.
        resolved_at:
          type: string
          format: date-time
          example: '2025-09-05T18:20:34Z'
          description: ISO-8601 formatted timestamp for when this escalation was resolved.
        severity:
          type: string
          enum:
          - low
          - high
          - critical
          example: low
          description: The severity of the escalation.
        status:
          type: string
          enum:
          - open
          - sent
          - resolved
          example: resolved
          description: The status of the Escalation
        subject:
          type: string
          example: Defender Disabled
          description: The subject of the Escalation
        subtype:
          type: string
          example: US
          description: An additional classifier for the escalation. The interpretation depends on the escalation type (e.g. an ISO country code for Unexpected Country Access escalations).
        type:
          type: string
          example: Environmental Issue
          description: The type of the Escalation
        updated_at:
          type: string
          format: date-time
          example: '2025-09-05T18:20:34Z'
          description: ISO-8601 formatted timestamp for when this escalation was last updated.
        entities:
          type: Object
          example:
            total_count: 1
            has_more: false
            items:
            - id: 1
              type: Agent
              details:
                hostname: laptop01
                platform: windows
                os: Windows 8 Pro
                last_callback_at: '2025-09-05T18:20:35Z'
          description: Object containing information about Entities associated with the escalation.
      required:
      - entities
      description: EscalationWithEntities model
    Escalation:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 84938
          description: A Huntress-unique identifier for the escalation.
        account:
          type: Account
          example:
            id: 1
            name: Your Account Name
          description: The Account the escalation pertains to.
        organizations:
          type: array
          items:
            type: string
          example:
          - id: 1234
            name: ExampleCo
          description: An array of Organizations this escalation pertains to
        created_at:
          type: string
          format: date-time
          example: '2025-09-05T18:20:34Z'
          description: ISO-8601 formatted timestamp for when this escalation was created.
        resolved_at:
          type: string
          format: date-time
          example: '2025-09-05T18:20:34Z'
          description: ISO-8601 formatted timestamp for when this escalation was resolved.
        severity:
          type: string
          enum:
          - low
          - high
          - critical
          example: low
          description: The severity of the escalation.
        status:
          type: string
          enum:
          - open
          - sent
          - resolved
          example: resolved
          description: The status of the Escalation
        subject:
          type: string
          example: Defender Disabled
          description: The subject of the Escalation
        subtype:
          type: string
          example: US
          description: An additional classifier for the escalation. The interpretation depends on the escalation type (e.g. an ISO country code for Unexpected Country Access escalations).
        type:
          type: string
          example: Environmental Issue
          description: The type of the Escalation
        updated_at:
          type: string
          format: date-time
          example: '2025-09-05T18:20:34Z'
          description: ISO-8601 formatted timestamp for when this escalation was last updated.
      description: Escalation model
    Pagination:
      type: object
      properties:
        next_page_url:
          type: string
        next_page_token:
          type: string
      description: Pagination model
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic