swagger: '2.0'
info:
title: Huntress API Reference Accounts Organizations 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: Organizations
description: Operations about Organizations
paths:
/v1/organizations:
get:
summary: List Organizations
description: "Shows details of Organizations belonging to the account associated with your API credentials.\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
- name
- key
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: name
description: Filter by organization name.
type: string
required: false
- in: query
name: key
description: Filter by organization key.
type: string
required: false
responses:
'200':
description: List Organizations
schema:
type: object
properties:
organizations:
type: array
items:
$ref: '#/definitions/Organization'
pagination:
$ref: '#/definitions/Pagination'
required:
- organizations
- pagination
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Organization'
tags:
- Organizations
operationId: getV1Organizations
post:
summary: Create an Organization
description: ''
produces:
- application/json
consumes:
- application/json
parameters:
- name: OrganizationCreationParameters
in: body
required: true
schema:
$ref: '#/definitions/OrganizationCreationParameters'
responses:
'201':
description: Create an Organization
schema:
type: object
properties:
organization:
$ref: '#/definitions/Organization'
'400':
description: Something about the request is malformed.
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Organization'
'422':
description: Invalid creation parameters.
tags:
- Organizations
operationId: OrganizationCreationParameters
/v1/organizations/{id}:
get:
summary: Get Organization
description: Shows details on a single Organization associated with your account.
produces:
- application/json
parameters:
- in: path
name: id
description: Organization ID within Huntress account
type: integer
format: int32
required: true
responses:
'200':
description: Get Organization
schema:
type: object
properties:
organization:
$ref: '#/definitions/OrganizationWithActualProductUsages'
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Organization'
tags:
- Organizations
operationId: getV1OrganizationsId
patch:
summary: Update an Organization
description: ''
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
- name: OrganizationUpdateParameters
in: body
required: true
schema:
$ref: '#/definitions/OrganizationUpdateParameters'
responses:
'200':
description: Update an Organization
schema:
type: object
properties:
organization:
$ref: '#/definitions/Organization'
'400':
description: Something about the request is malformed.
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Organization'
'422':
description: Invalid update parameters.
tags:
- Organizations
operationId: OrganizationUpdateParameters
delete:
summary: Delete an Organization
description: 'Deletes the specified Organization.
**Please note:** This will remove the organization and associated configurations across the Huntress Platform, including Managed SAT. For more information, see our [offboarding guide](https://support.huntress.io/hc/en-us/articles/51332785737235-Huntress-Product-Offboarding-Guide).
'
produces:
- application/json
parameters:
- in: path
name: id
description: The id of the organization to be deleted
type: integer
format: int32
required: true
responses:
'202':
description: Organization deleted
schema:
type: object
properties:
organization:
$ref: '#/definitions/Organization'
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Organization'
'404':
description: Organization not found, possibly because it has already been deleted.
'409':
description: There is a conflict about the organization that prevents deletion. See error message for more details.
'422':
description: Failed to delete organization. Please contact support.
tags:
- Organizations
operationId: deleteV1OrganizationsId
definitions:
OrganizationUpdateParameters:
type: object
properties:
name:
type: string
description: The name of the organization. Value cannot be blank and must be 256 characters or less.
example: Most Amazing Company, Ltd.
key:
type: string
description: Organization keys are used to associate a Huntress Agent into a grouping. Value cannot be blank and must be 256 characters or less.
example: amazing
report_recipients:
type: array
description: Any emails specified here will automatically receive quarterly and monthly branded reports.
example:
- vera@bradley.com
- my@user.net
items: null
description: Update an Organization
Organization:
type: object
properties:
id:
type: integer
format: int64
example: 1
description: A Huntress-unique identifier for the organization.
agents_count:
type: integer
format: int64
example: 42
description: Number of all agents for the organization.
account_id:
type: integer
format: int64
example: 5
description: The unique identifier of the account associated with the organization.
created_at:
type: string
format: date-time
example: '2022-03-01T18:54:02Z'
description: A timestamp for when the organization was created, formatted as per ISO-8601.
incident_reports_count:
type: integer
format: int64
example: 42
description: Number of incident reports for the organization.
key:
type: string
example: test1
description: The subdomain associated with the organization.
logs_sources_count:
type: integer
format: int64
example: 42
description: Number of SIEM log sources that are billable and eligible for billing.
identity_provider_tenant_id:
type: string
example: dcd219dd-bc68-4b9b-bf0b-4a33a796be35
description: The Identity Provider Tenant ID associated with the organization
billable_identity_count:
type: integer
format: int64
example: 42
description: Number of billable identities for the organization.
name:
type: string
example: Acme Inc.
description: The public facing name for this organization.
report_recipients:
type: array
items:
type: string
example:
- test@test.com
- fakenotificiation@test.com
description: A list of emails Huntress is configured to send notification emails for the organization.
sat_learner_count:
type: integer
format: int64
example: 42
description: Number of SAT learners.
updated_at:
type: string
format: date-time
example: '2022-03-01T18:54:02Z'
description: A timestamp for when the organization was updated, formatted as per ISO-8601.
required:
- microsoft_365_tenant_id
- microsoft_365_users_count
- notify_emails
description: Organization model
OrganizationWithActualProductUsages:
type: object
properties:
id:
type: integer
format: int64
example: 1
description: A Huntress-unique identifier for the organization.
agents_count:
type: integer
format: int64
example: 42
description: Number of all agents for the organization.
account_id:
type: integer
format: int64
example: 5
description: The unique identifier of the account associated with the organization.
created_at:
type: string
format: date-time
example: '2022-03-01T18:54:02Z'
description: A timestamp for when the organization was created, formatted as per ISO-8601.
incident_reports_count:
type: integer
format: int64
example: 42
description: Number of incident reports for the organization.
key:
type: string
example: test1
description: The subdomain associated with the organization.
logs_sources_count:
type: integer
format: int64
example: 42
description: Number of SIEM log sources that are billable and eligible for billing.
identity_provider_tenant_id:
type: string
example: dcd219dd-bc68-4b9b-bf0b-4a33a796be35
description: The Identity Provider Tenant ID associated with the organization
billable_identity_count:
type: integer
format: int64
example: 42
description: Number of billable identities for the organization.
name:
type: string
example: Acme Inc.
description: The public facing name for this organization.
report_recipients:
type: array
items:
type: string
example:
- test@test.com
- fakenotificiation@test.com
description: A list of emails Huntress is configured to send notification emails for the organization.
sat_learner_count:
type: integer
format: int64
example: 42
description: Number of SAT learners.
updated_at:
type: string
format: date-time
example: '2022-03-01T18:54:02Z'
description: A timestamp for when the organization was updated, formatted as per ISO-8601.
actual_usages:
type: string
example:
siem:
billable_log_sources_count: 5
retention: 90/7
current_billing_cycle:
online_gb: 12.34
service_period_start: '2026-04-15T00:00:00Z'
service_period_end: '2026-05-15T00:00:00Z'
previous_billing_cycle:
online_gb: 10.5
service_period_start: '2026-03-15T00:00:00Z'
service_period_end: '2026-04-15T00:00:00Z'
edr:
billable_agents_count: 42
unresponsive_agents_count: 2
outdated_agents_count: 1
isolated_agents_count: 0
sat:
learners_count: 25
ispm:
- type: microsoft
identity_provider_tenant_id: abcd-1234
billable_identities_count: 100
total_identities_count: 150
itdr:
- type: microsoft
identity_provider_tenant_id: abcd-1234
billable_identities_count: 100
total_identities_count: 150
- type: google
identity_provider_tenant_id: efgh-5678
billable_identities_count: 50
total_identities_count: 75
description: Actual usage metrics for the organization's active products, broken down by product type. **NOTE:** log usage data has a max retention of 90 days.
required:
- microsoft_365_tenant_id
- microsoft_365_users_count
- notify_emails
description: OrganizationWithActualProductUsages model
Pagination:
type: object
properties:
next_page_url:
type: string
next_page_token:
type: string
description: Pagination model
OrganizationCreationParameters:
type: object
properties:
name:
type: string
description: The name of the organization. Value cannot be blank and must be 256 characters or less.
example: Most Amazing Company, Ltd.
key:
type: string
description: Organization keys are used to associate a Huntress Agent into a grouping. Value cannot be blank and must be 256 characters or less.
example: amazing
required:
- name
- key
description: Create an Organization
securityDefinitions:
basic_auth:
type: basic
desc: Base 64 encoded string of your Huntress Account API key and API secret.