Huntress Agents API

openapi: 3.2.0
info:
  title: Huntress API Reference Agents 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: Agents
  description: Operations about Agents
paths:
  /v1/agents:
    get:
      summary: List Agents
      description: 'Shows Agents 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: organization_id
        description: Filter by organization ID within Huntress account
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: platform
        description: Filter by platform. One of windows, darwin, linux
        required: false
        schema:
          type: string
          enum:
          - windows
          - darwin
          - linux
      - in: query
        name: hostname
        description: Filter by hostname.
        required: false
        schema:
          type: string
      - in: query
        name: os
        description: Filter by operating system.
        required: false
        schema:
          type: string
      - in: query
        name: version
        description: Filter by agent version.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List Agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - agents
                - pagination
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
      tags:
      - Agents
      operationId: getV1Agents
  /v1/agents/{id}:
    get:
      summary: Get Agent
      description: Shows details on a single Agent associated with your account.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get Agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
      tags:
      - Agents
      operationId: getV1AgentsId
    patch:
      summary: Update Agent
      description: 'Updates the editable attributes of a single Agent.


        **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:
        '200':
          description: Update Agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '404':
          description: Agent not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '409':
          description: Agent does not support tamper protection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
      tags:
      - Agents
      operationId: UpdateAgent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgent'
        required: true
    delete:
      summary: Uninstall Agent
      description: 'Schedules a remote uninstall of a single Agent, removing the Huntress agent

        from the host. Uninstall is asynchronous: the host is tasked to uninstall on

        its next callback, and the Agent is immediately removed from your account, so

        subsequent requests for it return 404.


        This endpoint requires an API key with permission to uninstall agents.

        **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:
        '204':
          description: Agent scheduled for uninstall.
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '404':
          description: Agent not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
      tags:
      - Agents
      operationId: UninstallAgent
  /v1/agents/{id}/isolation:
    post:
      summary: Isolate Agent
      description: 'Schedules host isolation for a single Agent, cutting the host off from the

        network while leaving Huntress connectivity intact. Isolation is asynchronous:

        a successful request returns the Agent with a `firewall_status` of

        "Pending Isolation" until the endpoint confirms isolation.


        This endpoint requires an API key with permission to isolate agents.

        **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: Isolate Agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '403':
          description: There was an issue with your API credential or permissions.
        '404':
          description: Agent not found.
        '409':
          description: Agent does not support host isolation, or isolation could not be scheduled.
      tags:
      - Agents
      operationId: IsolateAgent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IsolateAgent'
        required: true
    delete:
      summary: Release Agent Isolation
      description: 'Schedules release of host isolation for a single Agent, restoring the host''s

        network connectivity. Release is asynchronous: a successful request returns the

        Agent with a `firewall_status` of "Pending Release" until the endpoint confirms

        the host is back online.


        This endpoint requires an API key with permission to release agents.

        **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:
        '204':
          description: There was an issue with your API credential or permissions.
        '404':
          description: Agent not found.
        '409':
          description: Agent does not support host isolation, or release could not be scheduled.
      tags:
      - Agents
      operationId: ReleaseAgent
components:
  schemas:
    IsolateAgent:
      type: object
      properties:
        reason:
          type: string
          description: Reason recorded for the isolation.
        strict_isolation:
          type: boolean
          description: Apply strict isolation. Only honored on Windows (WFP) and Linux (eBPF).
          default: false
      description: Isolate Agent
    Pagination:
      type: object
      properties:
        next_page_url:
          type: string
        next_page_token:
          type: string
      description: Pagination model
    UpdateAgent:
      type: object
      properties:
        tags:
          type: array
          description: The full set of user classifications on the host. The supplied list replaces any existing tags. Values are normalized to lowercase, hyphenated values (for example, "My Server" becomes "my-server"), and blank or duplicate values are dropped.
          items:
            type: object
            properties:
              ? ''
              : type: array
                description: The full set of user classifications on the host. The supplied list replaces any existing tags. Values are normalized to lowercase, hyphenated values (for example, "My Server" becomes "my-server"), and blank or duplicate values are dropped.
                items:
                  type: string
        tamper_protection_configured:
          type: boolean
          description: Enable or disable EDR tamper protection for the agent. Applies asynchronously, so the host-reported state is exposed separately as tamper_protection_actual. Requires an API key with permission to manage agent security settings, and the agent must support tamper protection.
      description: Update Agent
    Agent:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: A unique identifier for an agent.
        account_id:
          type: integer
          format: int64
          example: 5
          description: The unique identifier of the account associated with the agent.
        arch:
          type: string
          example: x86_64
          description: The architecture on the host machine.
        created_at:
          type: string
          format: date-time
          example: '2022-03-01T20:05:10Z'
          description: A timestamp for when the agent was created, formatted as per ISO-8601.
        domain_name:
          type: string
          example: WORKGROUP
          description: Domain that refers to the host machine.
        edr_version:
          type: string
          example: 0.3.20
          description: The semantic versioning number of the Huntress EDR software installed on the machine or `null` if EDR is not installed.
        external_ip:
          type: string
          example: 198.51.100.42
          description: The external IP of the host machine, if applicable.
        hostname:
          type: string
          example: laptop01
          description: The hostname of the host machine.
        defender_policy_status:
          type: string
          example: Compliant
          description: Policy status of Defender AV for Managed Antivirus.
        defender_status:
          type: string
          example: Healthy
          description: Status of Defender AV Managed Antivirus.
        defender_substatus:
          type: string
          example: Up to date
          description: Sub-status of Defender AV Managed Antivirus.
        firewall_status:
          type: string
          example: Disabled
          description: Status of agent firewall. Can be one of Disabled, Enabled, Pending Isolation, Isolated, Pending Release
        tamper_protection_configured:
          type: boolean
          example: true
          description: The desired EDR tamper protection state for the agent. `null` when the agent does not support tamper protection.
        tamper_protection_actual:
          type: boolean
          example: true
          description: The tamper protection state most recently reported by the host. May lag `tamper_protection_configured` and is `null` until the host reports.
        ipv4_address:
          type: string
          example: 146.134.139.9
          description: The internal IP of the host machine.
        last_callback_at:
          type: string
          format: date-time
          example: '2022-03-01T20:05:10Z'
          description: A timestamp for when the last time Huntress was able to access the host machine.
        last_survey_at:
          type: string
          format: date-time
          example: '2022-03-01T20:05:10Z'
          description: A timestamp for when the last Microsoft Defender survey was received by Huntress for this host machine.
        mac_addresses:
          type: array
          items:
            type: string
          example:
          - 7c:a7:b0:16:2f:78
          description: The unique media access control (MAC) addresses associated with the agent.
        service_pack_major:
          type: integer
          format: int32
          example: 0
          description: The major version of the Windows service pack installed on the host machine.
        service_pack_minor:
          type: integer
          format: int32
          example: 0
          description: The minor version of the Windows service pack installed on the host machine.
        organization_id:
          type: integer
          format: int64
          example: 7
          description: The unique identifier of the organization associated with the agent.
        os:
          type: string
          example: Windows 8 Pro
          description: The operating system of the host machine.
        os_build_version:
          type: string
          example: '19044'
          description: The operating system build number of the host machine corresponding to its platform (<a href='https://learn.microsoft.com/en-us/windows/release-health/windows11-release-information'>windows</a> or <a href='https://developer.apple.com/news/releases/'>darwin</a>).
        os_major:
          type: integer
          format: int32
          example: 6
          description: The major OS version of the host machine. Corresponds with the major releases of Windows operating systems. A list is accessible <a href='https://docs.microsoft.com/en-us/windows/win32/sysinfo/operating-system-version'>here</a>.
        os_minor:
          type: integer
          format: int32
          example: 2
          description: ' The minor OS version of the host machine. Refer to the `os_major` field details for further details.'
        os_patch:
          type: integer
          format: int32
          example: 0
          description: The patch version of the macOS update installed on the host machine, such as 1 in version 12.5.1.
        platform:
          type: string
          example: windows
          description: The platform of the host machine (`darwin`, `windows`, or `linux`).
        serial_number:
          type: string
          example: wtIe1bvDbh
          description: The serial number of the host machine as reported to the operating system.
        tags:
          type: array
          items:
            type: string
          example:
          - Server
          - Production
          description: User classifications on the host machine.
        updated_at:
          type: string
          format: date-time
          example: '2022-03-01T20:05:10Z'
          description: A timestamp for when the agent was last updated, formatted as per ISO-8601.
        version:
          type: string
          example: 0.11.3
          description: The semantic versioning number of the agent installed on the host machine.
        version_number:
          type: integer
          format: int32
          example: 720899
          description: Windows version number.
        win_build_number:
          type: integer
          format: int32
          example: 19044
          description: The Windows Build Number. Should correspond to information on the <a href='https://docs.microsoft.com/en-us/windows/release-health/release-information'>Microsoft site</a>.
      description: Agent model
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic