swagger: '2.0'
info:
title: Huntress API Reference Accounts Agents API
description: "\n© Huntress - All rights reserved
\nIntroduction
\n\nWebhook event payloads are available via the dropdown menu above the search bar on this page.
\n\nThe Huntress API follows a RESTful pattern. Requests are made via resource-oriented URLs as described in this document and API responses are formatted as JSON data.
\n\nA command-line client is also available for interacting with the API from your terminal. It requires Ruby 3.1+ and has no external dependencies. You can download it from https://api.huntress.io/api/huntress-cli.
\n\nAlternatively, if you'd prefer to use an MCP, we have instructions for setting up the Huntress MCP. Note that the MCP is read-only, so this is a good option if you're looking for a safer way to access your Huntress data from an LLM.
\n\nIf you'd like to request additional API endpoints or capabilities, submit feedback through our feedback portal.
\n\nAPI Overview
\n\n\tAuthentication
\n$KEY = echo \"$HUNTRESS_PUBLIC_KEY:$HUNTRESS_PRIVATE_KEY\" | base64\ncurl \"https://api.huntress.io/v1/agents\" \\ -H \"Authorization: Basic $KEY\"\n
\n
To begin, generate your API Key at <your_account_subdomain>.huntress.io. Once you are logged into your account on the Huntress site, check the dropdown menu at the top-right corner of the site header. You should see API Credentials among the options if your account has been granted access to the Huntress API. Click on the option to continue to the API Key generation page.
\n\nOnce on the API Key generation page, click on the green Setup button to begin the process to generate your API Key. You will be redirected to a page where you will be prompted to generate your API Key. Click the Generate button to generate a public and private key pair for Huntress API access. The inputs on the page will be filled in with your access credentials once you have done so.
\n\nYour API Private Key will only be visible at this stage of API Key generation. Be sure to save the value provided somewhere secure, as once you navigate away from this page, this value will no longer be accessible and you must regenerate your API credentials if your secret key value is lost.
\n\nIf necessary, you can repeat the process to regenerate your API credentials with a new API Key and API Secret Key on the same API Key generation page, at <your_account_subdomain>.huntress.io/account/api_credentials.
\n\nThe Huntress API implements basic access authentication. Once you have your API Key and API Secret Key, provide these values as the result of a Base64 encoded string in every request to the Huntress API via the Authorization header. Your request header should look something like Authorization: Basic [Base64Encode(<your_api_key>:<your_api_secret_key>)]. Please refer to the code snippets for further examples.
\n \n\n\tRate Limits
\nEvery Huntress API account is rate limited to 60 requests per minute, on a sliding window. This means that no more than 60 requests can be made within a 60 second time interval between the first request and the last request.
\n\nFor example, if request 1 is made at T0, request 2 is made at T5, and requests 3 through 60 are made at T10, making request 61 at T55 would result in a 429 error response. Making request 61 at T61 would succeed, however making request 62 at T61 would fail, at least until the time has passed T65, corresponding to a minute after request 2 was made.
\n \n\n\tHTTP Response Codes
\nHuntress follows HTTP standards when delivering responses: a 2xx response is a success, a 4xx response indicates an issue with the client request, and a 5xx response indicates an issue with Huntress servers.\n
\n
\nSpecific error codes are detailed in the following table:
\n\n\n| Error Status Code | \nDetails | \n
\n\n\n| 400 | \nThere is an unexpected value in the API request being made. | \n
\n\n| 401 | \nYour request could not be authenticated. Check that your API key is properly formatted and included in the Authorization header. | \n
\n\n| 404 | \nThe requested resource is unavailable: either it doesn't exist, or your account does not hold correct permissions to access it. | \n
\n\n| 429 | \nYou have made too many requests within the rate limit timeframe. See the previous section on rate_limits for details. | \n
\n\n| 500 | \nAn error has occurred within Huntress servers. You could retry the request, but if you encounter continued errors, please contact Support with details of your error. If all traffic from Huntress is resulting in 500 responses, please check our Huntress Status Page. | \n
\n
\n \n\n\t
\nCertain Huntress API endpoints utilize a page_token and limit parameter to specify a window location and size, respectively, to the resources currently being requested.\n
\nEach API request will also return a pagination object with details about your current pagination state based on the parameters provided. The pagination object contains:
\n\n\n\n| Key | \nType | \nDescription | \n
\n\n\n| next_page_token | \nstring | \nThe token used to request the next page in paginated results. If no page token is included, the first page contains all results. | \n
\n\n| next_page_url | \nstring | \nURL containing the next page and the limit provided in the original API request, to be used to continue sequentially accessing resources. Only displays when another page can be accessed. | \n
\n
\n
\nFollowing is a formatted example of the pagination object in an API response:
\n
\n
\n\"pagination\": {\n \"next_page_url\": \"https://api.huntress.io/v1/agents?page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo&limit=10\",\n \"next_page_token\": \"MjAyMi0wMy0wMVQxODo1NDoyNFo\"\n}
\n
\n\n\t
\n\t\n\t\tRequest
\n\t\n
\ncurl \"https://api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo\" -H \"Authorization: Basic <Your B64 encoded hash>\"
The base URL for API requests is api.huntress.io/v1/, followed by the resource requested. Resources can be requested either singularly or as a list, which correspond to /v1/<resources>/:id or /v1/<resources> respectively, with the exception of the /v1/account and /v1/actor endpoints, which only returns the account associated with the API credentials provided.
\n\tAs an example, api.huntress.io/v1/agents would return a list of agents, while api.huntress.io/v1/agents/1 would return a singular agent with ID: 1.
\n\tParameters are provided to the API through a query string. As an example, providing the organization_id filter as a parameter to the /v1/agents endpoint would look like api.huntress/io/v1/agents?organization_id=1. Accessing a sequential page with the same filter active would look like api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo.
\n\t \n\t\n\t\tResponse
\n\tThe Huntress API responds with a JSON object containing requested resources if the request is valid and authorized.
\n\tSingular Case
\n\t\n\t
{\n \"report\": { ... }\n}\n
In the case of accessing a singular resource, the JSON object in question will contain one key that maps the singular resource to the singular representation of the resource name. As an example, if you were to request api.huntress.io/v1/reports/1, the JSON response would contain a single key report that maps to the report with ID: 1.
\n\tMultiple Case
\n{\n \"reports\": [ ... ],\n \"pagination\": { ... }\n}\n
When accessing a list of resources, the JSON response contains two keys at the root level. The first key is the plural representation of that resource. The second is a pagination key that represents the current state of pagination based on parameters provided in the original request. As an example, a request to api.huntress.io/v1/reports returns a JSON object with the keys reports and pagination at its root level. Further details on the fields within the pagination object can be seen at the relevant section.
\n\t \n \n"
version: 1.0.0
host: api.huntress.io
schemes:
- https
produces:
- application/json
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.\n\n**Note:** This endpoint will also return a `pagination` key on the root level. \nPlease refer to the [pagination section](https://api.huntress.io/docs#pagination) within our docs for more information.\n"
produces:
- application/json
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.
type: integer
format: int32
default: 10
minimum: 1
maximum: 500
required: false
- in: query
name: page_token
description: Token used to request the next page in paginated results. Defaults to 'null'
type: string
required: false
- in: query
name: sort_field
description: Field to sort by. Defaults to 'id'.
type: string
default: id
enum:
- id
- created_at
- updated_at
required: false
- in: query
name: sort_direction
description: Sort direction. Defaults to 'desc'.
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: organization_id
description: Filter by organization ID within Huntress account
type: integer
format: int32
required: false
- in: query
name: platform
description: Filter by platform. One of windows, darwin, linux
type: string
enum:
- windows
- darwin
- linux
required: false
- in: query
name: hostname
description: Filter by hostname.
type: string
required: false
- in: query
name: os
description: Filter by operating system.
type: string
required: false
- in: query
name: version
description: Filter by agent version.
type: string
required: false
responses:
'200':
description: List Agents
schema:
type: object
properties:
agents:
type: array
items:
$ref: '#/definitions/Agent'
pagination:
$ref: '#/definitions/Pagination'
required:
- agents
- pagination
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Agent'
tags:
- Agents
operationId: getV1Agents
/v1/agents/{id}:
get:
summary: Get Agent
description: Shows details on a single Agent associated with your account.
produces:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
responses:
'200':
description: Get Agent
schema:
type: object
properties:
agent:
$ref: '#/definitions/Agent'
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/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.**
'
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
- name: UpdateAgent
in: body
required: true
schema:
$ref: '#/definitions/UpdateAgent'
responses:
'200':
description: Update Agent
schema:
type: object
properties:
agent:
$ref: '#/definitions/Agent'
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Agent'
'404':
description: Agent not found.
schema:
$ref: '#/definitions/Agent'
'409':
description: Agent does not support tamper protection.
schema:
$ref: '#/definitions/Agent'
tags:
- Agents
operationId: UpdateAgent
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.**
'
produces:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
responses:
'204':
description: Agent scheduled for uninstall.
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Agent'
'404':
description: Agent not found.
schema:
$ref: '#/definitions/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.**
'
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
- name: IsolateAgent
in: body
required: true
schema:
$ref: '#/definitions/IsolateAgent'
responses:
'201':
description: Isolate Agent
schema:
type: object
properties:
agent:
$ref: '#/definitions/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
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.**
'
produces:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
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
definitions:
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
Pagination:
type: object
properties:
next_page_url:
type: string
next_page_token:
type: string
description: Pagination model
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 (windows or darwin).
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 here.
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 Microsoft site.
description: Agent model
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
securityDefinitions:
basic_auth:
type: basic
desc: Base 64 encoded string of your Huntress Account API key and API secret.