swagger: '2.0' info: title: Huntress API Reference Accounts Unwanted Access Rules API description: "\n

© Huntress - All rights reserved

\n

Introduction

\n\n

Webhook event payloads are available via the dropdown menu above the search bar on this page.

\n\n

The 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\n

A 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\n

Alternatively, 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\n

If you'd like to request additional API endpoints or capabilities, submit feedback through our feedback portal.

\n\n

API Overview

\n
\n\t

Authentication

\n
$KEY = echo \"$HUNTRESS_PUBLIC_KEY:$HUNTRESS_PRIVATE_KEY\" | base64\ncurl \"https://api.huntress.io/v1/agents\" \\ -H \"Authorization: Basic $KEY\"\n
\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\n

Once 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\n

Your 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\n

If 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\n

The 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\t

Rate Limits

\n

Every 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\n

For 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\t

HTTP Response Codes

\n

Huntress 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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Error Status CodeDetails
400There is an unexpected value in the API request being made.
401Your request could not be authenticated. Check that your API key is properly formatted and included in the Authorization header.
404The requested resource is unavailable: either it doesn't exist, or your account does not hold correct permissions to access it.
429You have made too many requests within the rate limit timeframe. See the previous section on rate_limits for details.
500

An 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\t

Pagination

\n

Certain 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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KeyTypeDescription
next_page_tokenstringThe token used to request the next page in paginated results. If no page token is included, the first page contains all results.
next_page_urlstringURL 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

Following 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
\n\t

Request and Response Format

\n\t
\n\t\t

Request

\n\t
\n
\ncurl \"https://api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo\" -H \"Authorization: Basic <Your B64 encoded hash>\"
\n\t

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\t

As 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\t

Parameters 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\t

Response

\n\t

The Huntress API responds with a JSON object containing requested resources if the request is valid and authorized.

\n\t

Singular Case

\n\t
\n\t
{\n  \"report\": { ... }\n}\n
\n\t

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\t

Multiple Case

\n
{\n  \"reports\": [ ... ],\n  \"pagination\": { ... }\n}\n
\n\t

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: Unwanted Access Rules description: Operations about Unwanted Access Rules paths: /v1/unwanted_access_rules: get: summary: List Unwanted Access Rules description: 'Shows Unwanted Access Rules associated with your account. Unwanted Access Rules govern how Huntress responds to identity access attempts matching specific attributes. Each rule targets a category (country, vpn, ip_address) and declares a determination — `expected` or `unauthorized` — at the account, organization, or identity scope. **Note:** This endpoint will also return a `pagination` key on the root level. Please refer to the [pagination section](https://api.huntress.io/docs#pagination) within our docs for more information. ' 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: organization_id description: Filter by organization ID within Huntress account. type: integer format: int32 required: false - in: query name: identity_id description: Filter results to rules attached directly to this identity. type: integer format: int32 required: false - in: query name: type description: Filter by rule type. type: string enum: - expected - unauthorized required: false - in: query name: status description: Filter by rule status as shown in the Portal UI. type: string enum: - active - scheduled - expired required: false - in: query name: scope description: Filter by the level the rule is attached to. type: string enum: - account - organization - identity required: false - in: query name: category description: Limit results to a single rule category. type: string enum: - country - vpn - ip_address required: false - in: query name: country_code description: Filter by country code value (ISO 3166-1 alpha-2). Implies `category=country`. type: string required: false - in: query name: vpn description: Filter by VPN (tunnel operator) value. Implies `category=vpn`. type: string required: false - in: query name: ip_address description: Filter by IP Address value. Implies `category=ip_address`. type: string required: false - in: query name: logic description: 'Filter by rule logic. `standard` returns rules with explicit values, `catchall` returns rules matching all values in a category, and `catchall_exception` returns rules that exclude specifically set values from an existing catchall rule. Omit this parameter to include all three. ' type: string enum: - standard - catchall - catchall_exception required: false responses: '200': description: List Unwanted Access Rules schema: type: object properties: unwanted_access_rules: type: array items: $ref: '#/definitions/UnwantedAccessRule' pagination: $ref: '#/definitions/Pagination' required: - unwanted_access_rules - pagination '400': description: Invalid request parameters. schema: $ref: '#/definitions/UnwantedAccessRule' '403': description: There was an issue with your API credential or permissions. schema: $ref: '#/definitions/UnwantedAccessRule' tags: - Unwanted Access Rules operationId: getV1UnwantedAccessRules post: summary: Create an Unwanted Access Rule description: "Creates a new Unwanted Access Rule associated with your account, an organization, or a specific identity.\n\n**Rule logic.** Provide exactly one of `country_code`, `vpn`, or `logic`:\n - Omit `logic` and supply `country_code` or `vpn` to create `standard` rules. Provide a single value to create one rule, or a comma-separated list to create one `standard` rule per value in a single request. All rules share the same scope, type, and schedule, and are created atomically. If any value fails validation (for example a duplicate rule already exists), no rules are created. Duplicate values in the list are ignored. Only the last created rule is returned in the response.\n - Set `logic` as `catchall` (with `category`) to create a catchall rule that matches every value in the category. Catchalls must be `unauthorized` and may only be scoped to the account or an organization. An account or organization may have at most one catchall per category.\n - Set `logic` as `catchall_exception` (with `category`) to create an exception that opts an organization out of an account-level catchall. Exceptions must be `expected`, may only be scoped to an organization, and must omit `starts_at`/`expires_at`.\n\n**Scope.** The rule scope is determined by the IDs supplied: provide `identity_id` to scope the rule to a single identity, `organization_id` to scope it to an organization. Omitting both scopes the rule at the account level.\n" produces: - application/json consumes: - application/json parameters: - name: UnwantedAccessRuleCreationParameters in: body required: true schema: $ref: '#/definitions/UnwantedAccessRuleCreationParameters' responses: '201': description: Create an Unwanted Access Rule schema: type: object properties: unwanted_access_rule: $ref: '#/definitions/UnwantedAccessRule' '400': description: Invalid request parameters. '403': description: There was an issue with your API credential or permissions. '404': description: Specified organization or identity not found. '422': description: Invalid creation parameters. The rule failed validation — for example, a duplicate rule already exists, the scope is not allowed for the chosen logic, or the type/schedule fields conflict with the rule logic. tags: - Unwanted Access Rules operationId: UnwantedAccessRuleCreationParameters /v1/unwanted_access_rules/{id}: get: summary: Get Unwanted Access Rule description: Shows details on a single Unwanted Access Rule associated with your account. produces: - application/json parameters: - in: path name: id description: Unwanted Access Rule ID. type: integer format: int32 required: true responses: '200': description: Get Unwanted Access Rule schema: type: object properties: unwanted_access_rule: $ref: '#/definitions/UnwantedAccessRule' '403': description: There was an issue with your API credential or permissions. schema: $ref: '#/definitions/UnwantedAccessRule' '404': description: Unwanted Access Rule not found. schema: $ref: '#/definitions/UnwantedAccessRule' tags: - Unwanted Access Rules operationId: getV1UnwantedAccessRulesId delete: summary: Delete Unwanted Access Rule description: 'Deletes a single Unwanted Access Rule associated with your account. Standard, catchall, and catchall exception rules can all be deleted through this endpoint. ' produces: - application/json parameters: - in: path name: id description: Unwanted Access Rule ID. type: integer format: int32 required: true responses: '202': description: Unwanted Access Rule deleted schema: type: object properties: unwanted_access_rule: $ref: '#/definitions/UnwantedAccessRule' '403': description: There was an issue with your API credential or permissions. '404': description: Unwanted Access Rule not found or has already been deleted '422': description: Failed to delete unwanted access rule. Please contact support. tags: - Unwanted Access Rules operationId: deleteV1UnwantedAccessRulesId patch: summary: Update an Unwanted Access Rule description: 'Updates the schedule and notes on an existing Unwanted Access Rule. The rule''s category, value, scope, logic, and type cannot be changed. Standard, catchall, and catchall exception rules can all be updated, but catchall and catchall exception rules must keep `starts_at` and `expires_at` nil. Passing a value for those fields on those rules will return a 422. ' produces: - application/json consumes: - application/json parameters: - in: path name: id description: Unwanted Access Rule ID. type: integer format: int32 required: true - name: UnwantedAccessRuleUpdateParameters in: body required: true schema: $ref: '#/definitions/UnwantedAccessRuleUpdateParameters' responses: '200': description: Update an Unwanted Access Rule schema: type: object properties: unwanted_access_rule: $ref: '#/definitions/UnwantedAccessRule' '400': description: Invalid request parameters. '403': description: There was an issue with your API credential or permissions. '404': description: Unwanted Access Rule not found. '422': description: Invalid update parameters. tags: - Unwanted Access Rules operationId: UnwantedAccessRuleUpdateParameters definitions: Pagination: type: object properties: next_page_url: type: string next_page_token: type: string description: Pagination model UnwantedAccessRuleCreationParameters: type: object properties: identity_id: type: integer format: int32 description: Scope the rule to a specific identity. Mutually exclusive with `organization_id`. If neither is provided, the rule is scoped to the account. organization_id: type: integer format: int32 description: Scope the rule to an organization. Mutually exclusive with `identity_id`. If neither is provided, the rule is scoped to the account. country_code: type: string description: ISO 3166-1 alpha-2 country code(s) this rule should match. Provide for `standard` rules. Accepts a single code or a comma-separated list, which creates one rule per code. Mutually exclusive with `vpn` and `logic`. vpn: type: string description: Tunnel operator name(s) this rule should match. Provide for `standard` rules. Accepts a single name or a comma-separated list, which creates one rule per name. Mutually exclusive with `country_code` and `logic`. logic: type: string description: Rule logic. Set to `catchall` to match every value in a category, or `catchall_exception` to opt an organization out of an account-level catchall. Omit to create a `standard` rule (in which case `country_code` or `vpn` is required). Mutually exclusive with `country_code` and `vpn`. enum: - catchall - catchall_exception type: type: string description: Whether matching access is `expected` or `unauthorized`. Must be `unauthorized` when rule `logic` is `catchall` and `expected` when rule `logic` is `catchall_exception`. enum: - expected - unauthorized starts_at: type: string format: date description: UTC date (YYYY-MM-DD) when the rule becomes active. Omit for `expected` rules that should start immediately. Must be omitted for `unauthorized` rules and for rules with `logic` of `catchall` or `catchall_exception`. expires_at: type: string format: date description: UTC date (YYYY-MM-DD) when the rule expires. Omit for `expected` rules that should never expire. Must be omitted for `unauthorized` rules and for rules with `logic` of `catchall` or `catchall_exception`. notes: type: string description: Optional free-text note to attach to the rule. category: type: string description: Category that the catchall or exception applies to. Required when `logic` is provided. enum: - country - vpn required: - type description: Create an Unwanted Access Rule UnwantedAccessRuleUpdateParameters: type: object properties: starts_at: type: string format: date description: UTC date (YYYY-MM-DD) when the rule becomes active. Pass an empty string or null to clear. expires_at: type: string format: date description: UTC date (YYYY-MM-DD) when the rule expires. Pass an empty string or null to clear. notes: type: string description: Free-text note attached to the rule. Pass an empty string or null to clear. description: Update an Unwanted Access Rule UnwantedAccessRule: type: object properties: id: type: integer format: int64 example: 84938 description: A Huntress-unique identifier for the rule. applied_to: type: Object example: type: Organization id: 1234 name: ExampleCo description: The resource this rule applies to. category: type: string enum: - country - vpn - ip_address example: country description: The category of attribute this rule governs. country_code: type: string example: US description: ISO 3166-1 alpha-2 country code this rule matches. Null unless `category` is `country`. vpn: type: string example: NORD_VPN description: Tunnel operator name this rule matches. Null unless `category` is `vpn`. ip_address: type: string example: 203.0.113.0/24 description: IP Address this rule matches. Null unless `category` is `ip_address`. type: type: string enum: - expected - unauthorized example: unauthorized description: Whether matching access is expected or unauthorized. status: type: string enum: - active - scheduled - expired - not_applicable example: active description: The current status of the rule. logic: type: string enum: - catchall_exception - catchall - standard example: standard description: 'How the rule matches: `standard` matches a specific value within the `country`, `vpn`, or `ip_address` category, `catchall` matches all values in the category, and `catchall_exception` opts the resource out of an inherited catchall.' note: type: string example: Approved by compliance — regional office access description: Optional free-text note the rule author attached to the rule. starts_at: type: string format: date-time example: '2025-09-05T18:20:34Z' description: ISO-8601 formatted timestamp for when this rule becomes active. Null for unscheduled rules. expires_at: type: string format: date-time example: '2025-12-05T18:20:34Z' description: ISO-8601 formatted timestamp for when this rule expires. Null if the rule does not expire. created_by: type: string example: Jane Doe description: The name of the user who created this rule, or "Deleted" if the user has been removed. created_at: type: string format: date-time example: '2025-09-05T18:20:34Z' description: ISO-8601 formatted timestamp for when this rule was created. updated_at: type: string format: date-time example: '2025-09-05T18:20:34Z' description: ISO-8601 formatted timestamp for when this rule was last updated. description: UnwantedAccessRule model securityDefinitions: basic_auth: type: basic desc: Base 64 encoded string of your Huntress Account API key and API secret.