swagger: '2.0'
info:
title: Huntress API Reference Accounts Users API
description: "<!-- DO NOT LINT FOR FORMATTING, you will break how it appears on the docs site -->\n<p><a href='https://www.huntress.com/terms-of-service'>© Huntress - All rights reserved</a></p>\n<h1 id='introduction'>Introduction</h1>\n\n<p>Webhook event payloads are available via the dropdown menu above the search bar on this page.</p>\n\n<p>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.</p>\n\n<p>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 <a href='https://api.huntress.io/api/huntress-cli'>https://api.huntress.io/api/huntress-cli</a>.</p>\n\n<p>Alternatively, if you'd prefer to use an MCP, we have <a href=\"https://support.huntress.io/hc/en-us/articles/50846554117395-Connecting-to-the-Huntress-MCP-Server\">instructions for setting up the Huntress MCP</a>. 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.</p>\n\n<p>If you'd like to request additional API endpoints or capabilities, <a href=\"https://feedback.huntress.com/\">submit feedback</a> through our feedback portal.</p>\n\n<h1 id='api-overview'>API Overview</h1>\n<details>\n\t<summary><h2 id='authentication'>Authentication</h2></summary>\n<div class=\"scalar-code-copy\"><pre class=\"scalar-codeblock-pre\"><code class=\"hljs language-curl\"><span class=\"hljs-variable\">$KEY</span> = </span><span class=\"hljs-built_in\">echo </span><span class=\"hljs-string\">\"$HUNTRESS_PUBLIC_KEY:$HUNTRESS_PRIVATE_KEY\"</span> | <span class=\"hljs-built_in\">base64</span>\n<span class=\"hljs-built_in\">curl </span><span class=\"hljs-string\">\"https://api.huntress.io/v1/agents\"</span> \\ -H <span class=\"hljs-string\">\"Authorization: Basic $KEY\"</span>\n</code></pre>\n</div>\n<p>To begin, generate your API Key at <code><your_account_subdomain>.huntress.io</code>. 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 <code>API Credentials</code> 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.</p>\n\n<p>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.</p>\n\n<p><strong>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.</strong></p>\n\n<p>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 <code><your_account_subdomain>.huntress.io/account/api_credentials</code>.</p>\n\n<p>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 <code>Authorization</code> header. Your request header should look something like <code>Authorization: Basic [Base64Encode(<your_api_key>:<your_api_secret_key>)]</code>. Please refer to the code snippets for further examples.</p>\n</details>\n<details>\n\t<summary><h2 id='rate-limits'>Rate Limits</h2></summary>\n<p>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.</p>\n\n<p>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.</p>\n</details>\n<details>\n\t<summary><h2 id='http-response-codes'>HTTP Response Codes</h2></summary>\n<p>Huntress follows HTTP standards when delivering responses: a <code>2xx</code> response is a success, a <code>4xx</code> response indicates an issue with the client request, and a <code>5xx</code> response indicates an issue with Huntress servers.\n<br>\n<br>\nSpecific error codes are detailed in the following table:</p>\n<table><thead>\n<tr>\n<th>Error Status Code</th>\n<th>Details</th>\n</tr>\n</thead><tbody>\n<tr>\n<td>400</td>\n<td>There is an unexpected value in the API request being made.</td>\n</tr>\n<tr>\n<td>401</td>\n<td>Your request could not be authenticated. Check that your API key is properly formatted and included in the <code>Authorization</code> header.</td>\n</tr>\n<tr>\n<td>404</td>\n<td>The requested resource is unavailable: either it doesn't exist, or your account does not hold correct permissions to access it.</td>\n</tr>\n<tr>\n<td>429</td>\n<td>You have made too many requests within the rate limit timeframe. See the previous section on <a href=\"#rate_limits\">rate_limits</a> for details.</td>\n</tr>\n<tr>\n<td>500</td>\n<td><p>An error has occurred within Huntress servers.</p><p>You could retry the request, but if you encounter continued errors, please <a href=\"https://support.huntress.io\">contact Support</a> with details of your error. If all traffic from Huntress is resulting in 500 responses, please check our <a href=\"https://huntressstatus.statuspage.io/\">Huntress Status Page</a>.</p></td>\n</tr>\n</tbody></table>\n</details>\n<details>\n\t<summary><h2 id='pagination'>Pagination</h2></summary>\n<p>Certain Huntress API endpoints utilize a <code>page_token</code> and <code>limit</code> parameter to specify a window location and size, respectively, to the resources currently being requested.\n<br><br>\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:<br></p>\n\n<table><thead>\n<tr>\n<th>Key</th>\n<th>Type</th>\n<th>Description</th>\n</tr>\n</thead><tbody>\n<tr>\n<td>next_page_token</td>\n<td>string</td>\n<td>The token used to request the next page in paginated results. If no page token is included, the first page contains all results.</td>\n</tr>\n<tr>\n<td>next_page_url</td>\n<td>string</td>\n<td>URL 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.</td>\n</tr>\n</tbody></table>\n<br>\n<p>Following is a formatted example of the pagination object in an API response:<br>\n<div class=\"scalar-code-copy\">\n<pre class=\"scalar-codeblock-pre\">\n<code class=\"hljs language-json\"><span class=\"hljs-attr\">\"pagination\"</span><span class=\"hljs-punctuation\">: {</span>\n<span class=\"hljs-attr\"> \"next_page_url\"</span><span class=\"hljs-punctuation\">: </span><span class=\"hljs-string\">\"https://api.huntress.io/v1/agents?page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo&limit=10\"</span><span class=\"hljs-punctuation\">,\n</span><span class=\"hljs-attr\"> \"next_page_token\"</span><span class=\"hljs-punctuation\">: </span><span class=\"hljs-string\">\"MjAyMi0wMy0wMVQxODo1NDoyNFo\"</span><span class=\"hljs-punctuation\">\n}</span></code></pre>\n</div>\n</details>\n<details>\n\t<summary><h2 id='request-and-response-format'>Request and Response Format</h2></summary>\n\t<details>\n\t\t<summary><h3 id='request'>Request</h3></summary>\n\t<div class=\"scalar-code-copy\">\n<pre class=\"scalar-codeblock-pre\">\n<code class=\"hljs language-curl\"><span class=\"hljs-built_in\">curl</span> <span class=\"hljs-string\">\"https://api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo\"</span> -H <span class=\"hljs-string\">\"Authorization: Basic <Your B64 encoded hash>\"</span></code></pre></div>\n\t<p>The base URL for API requests is <code>api.huntress.io/v1/</code>, followed by the resource requested. Resources can be requested either singularly or as a list, which correspond to <code>/v1/<resources>/:id</code> or <code>/v1/<resources></code> respectively, with the exception of the <code>/v1/account</code> and <code>/v1/actor</code> endpoints, which only returns the account associated with the API credentials provided.</p>\n\t<p>As an example, <code>api.huntress.io/v1/agents</code> would return a list of agents, while <code>api.huntress.io/v1/agents/1</code> would return a singular agent with ID: 1.</p>\n\t<p>Parameters are provided to the API through a query string. As an example, providing the organization_id filter as a parameter to the <code>/v1/agents</code> endpoint would look like <code>api.huntress/io/v1/agents?organization_id=1</code>. Accessing a sequential page with the same filter active would look like <code>api.huntress.io/v1/agents?organization_id=1&page_token=MjAyMi0wMy0wMVQxODo1NDoyNFo</code>.</p>\n\t</details>\n\t<details>\n\t\t<summary><h3 id='response'>Response</h3></summary>\n\t<p>The Huntress API responds with a JSON object containing requested resources if the request is valid and authorized.</p>\n\t<h4 id='singular-case'>Singular Case</h4>\n\t<div class=\"scalar-code-copy\">\n\t<pre class=\"scalar-codeblock-pre\"><code class=\"hljs-json\"><span class=\"hljs-punctuation\">{</span>\n<span class=\"hljs-attr\"> \"report\"</span><span class=\"hljs-punctuation\">: { ... }\n}</span></code>\n</div>\n\t<p>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 <code>api.huntress.io/v1/reports/1</code>, the JSON response would contain a single key <code>report</code> that maps to the report with ID: 1.</p>\n\t<h4 id='multiple-case'>Multiple Case</h4><div class=\"highlight\"><pre class=\"highlight json tab-json\">\n<pre class=\"scalar-codeblock-pre\"><code class=\"hljs-json\"><span class=\"hljs-punctuation\">{</span>\n<span class=\"hljs-attr\"> \"reports\"</span><span class=\"hljs-punctuation\">: [ ... ],</span>\n<span class=\"hljs-attr\"> \"pagination\"</span><span class=\"hljs-punctuation\">: { ... }</span>\n<span class=\"hljs-punctuation\">}</span>\n</code></pre></div>\n\t<p>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 <code>pagination</code> key that represents the current state of pagination based on parameters provided in the original request. As an example, a request to <code>api.huntress.io/v1/reports</code> returns a JSON object with the keys <code>reports</code> and <code>pagination</code> at its root level. Further details on the fields within the pagination object can be seen at <a href=\"#pagination\">the relevant section</a>.</p>\n\t</details>\n</details>\n"
version: 1.0.0
host: api.huntress.io
schemes:
- https
produces:
- application/json
security:
- basic:
- basic_auth
tags:
- name: Users
description: Operations about Users
paths:
/v1/memberships:
get:
summary: List Memberships
description: "Shows a list of memberships.\n\nBy default, this endpoint returns both account and organization\nmemberships, but if an organization ID is supplied, it will return\nonly organization memberships, instead.\n\nThe example return value shows both an organization and an account, but\na given membership will only have one or the other.\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
- user_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 to return only memberships for that organization.
type: integer
format: int32
required: false
- in: query
name: user_id
description: Filter by user ID to return only memberships for that user.
type: integer
format: int32
required: false
- in: query
name: permissions
description: Filter by permission label.
type: string
enum:
- Admin
- Security Engineer
- User
- Read-only
- Finance
- Marketing
- Provisioner
required: false
responses:
'200':
description: List Memberships
schema:
type: object
properties:
memberships:
type: array
items:
$ref: '#/definitions/Membership'
pagination:
$ref: '#/definitions/Pagination'
required:
- memberships
- pagination
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Membership'
tags:
- Users
operationId: getV1Memberships
post:
summary: Create a Membership
description: 'This endpoint allows you to invite a user to join your organization or
account. A user will often be a person you wish to grant access to,
but it could also represent a team, an automated system, or any other
type of actor.
If an organization ID is provided, the user will be invited to that
organization. If not, they will be invited to the account associated
with this API credential. Note that while the sample return value
includes both an organization and an account for completeness, in
practice, only one or the other will be included.
Note that this is technically creating a Membership Invitation - the
actual membership won''t be created until the user accepts the
invitation.
'
produces:
- application/json
consumes:
- application/json
parameters:
- name: MembershipCreationParameters
in: body
required: true
schema:
$ref: '#/definitions/MembershipCreationParameters'
responses:
'201':
description: Create a Membership
schema:
type: object
properties:
member_invitation:
$ref: '#/definitions/MemberInvitation'
'400':
description: Something about the request is malformed.
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Membership'
'404':
description: Organization not found.
'422':
description: Invalid creation parameters.
tags:
- Users
operationId: MembershipCreationParameters
/v1/memberships/{id}:
get:
summary: Get Membership
description: Shows details on a single Membership associated with your account or organization.
produces:
- application/json
parameters:
- in: path
name: id
description: Membership ID within Huntress account
type: integer
format: int32
required: true
responses:
'200':
description: Get Membership
schema:
type: object
properties:
membership:
$ref: '#/definitions/Membership'
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Membership'
tags:
- Users
operationId: getV1MembershipsId
delete:
summary: Delete Membership
description: Deletes a single Membership associated with your account or organization. Does not delete the user associated with the membership.
produces:
- application/json
parameters:
- in: path
name: id
description: Membership ID within Huntress account
type: integer
format: int32
required: true
responses:
'202':
description: Membership deleted
schema:
type: object
properties:
membership:
$ref: '#/definitions/Membership'
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Membership'
'404':
description: Membership not found, possibly because it has already been deleted.
'422':
description: Failed to delete membership. Please contact support.
tags:
- Users
operationId: deleteV1MembershipsId
patch:
summary: Update a User's membership
description: ''
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: Membership ID within Huntress account
type: integer
format: int32
required: true
- name: MembershipUpdateParameters
in: body
required: true
schema:
$ref: '#/definitions/MembershipUpdateParameters'
responses:
'200':
description: Update a User's membership
schema:
type: object
properties:
membership:
$ref: '#/definitions/Membership'
'400':
description: Something about the request is malformed.
'403':
description: There was an issue with your API credential or permissions.
schema:
$ref: '#/definitions/Membership'
'422':
description: Something prevented the update.
tags:
- Users
operationId: MembershipUpdateParameters
definitions:
MemberInvitation:
type: object
properties:
permissions:
type: string
example: Read-only
description: The specific level of permissions that have been granted to this user in the context of this membership.
account:
type: Object
example:
id: 1234
name: Exemplary Accounting, LLC
description: The account associated with this membership (if any).
organization:
type: Object
example:
id: 5678
name: Organic Zations
description: The organization associated with this membership (if any).
user:
type: Object
example:
email: little_bobby@example.com
name: Robert Tables
description: The user associated with this membership.
description: MemberInvitation model
MembershipUpdateParameters:
type: object
properties:
permissions:
type: string
description: 'The specific level of permissions that have been granted to the user in the context of this membership. For more information, see our [support article](https://support.huntress.io/hc/en-us/articles/4404012728083-Huntress-Portal-User-Permissions) on permissions. Accepted values:
'
enum:
- Admin
- Finance
- Marketing
- Provisioner
- Read-only
- Security Engineer
- User
example: Security Engineer
description: Update a User's membership
Pagination:
type: object
properties:
next_page_url:
type: string
next_page_token:
type: string
description: Pagination model
Membership:
type: object
properties:
id:
type: integer
format: int64
example: 1
description: A unique identifier for this membership. Note that this is _not_ the id of the user, account, etc. Instead, it identifies this specific relationship, which can be used to modify or delete the membership.
permissions:
type: string
enum:
- Admin
- Security Engineer
- User
- Read-only
- Finance
- Marketing
- Admin-Read-only
- Provisioner
example: Read-only
description: The specific level of permissions that have been granted to this user in the context of this membership.
account:
type: Object
example:
id: 1234
name: Exemplary Accounting, LLC
description: The account associated with this membership (if any).
organization:
type: Object
example:
id: 5678
name: Organic Zations
description: The organization associated with this membership (if any).
user:
type: Object
example:
id: 90210
email: little_bobby@example.com
name: Robert Tables
description: The user associated with this membership.
created_at:
type: string
example: 2026-01-22 01:07:08 UTC
description: The time and date that this membership was created.
updated_at:
type: string
example: 2026-01-22 01:07:08 UTC
description: The time and date that this membership was last updated.
description: Membership model
MembershipCreationParameters:
type: object
properties:
email:
type: string
description: The email address of the user you are inviting.
example: accounting@example.com
first_name:
type: string
description: The first name of the user you are inviting.
example: Accounting
last_name:
type: string
description: The last name of the user you are inviting.
example: Department
permissions:
type: string
description: The specific permissions this membership will grant to the user.
enum:
- Admin
- Security Engineer
- User
- Read-only
- Finance
- Marketing
- Provisioner
example: Read-only
organization_id:
type: integer
format: int32
description: Include this parameter to invite a user to an organization instead of your account.
example: 123456
required:
- email
- first_name
- last_name
- permissions
description: Create a Membership
securityDefinitions:
basic_auth:
type: basic
desc: Base 64 encoded string of your Huntress Account API key and API secret.