Huntress Unwanted Access Rules API

openapi: 3.2.0
info:
  title: Huntress API Reference Unwanted Access Rules 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: 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 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: organization_id
        description: Filter by organization ID within Huntress account.
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: identity_id
        description: Filter results to rules attached directly to this identity.
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: type
        description: Filter by rule type.
        required: false
        schema:
          type: string
          enum:
          - expected
          - unauthorized
      - in: query
        name: status
        description: Filter by rule status as shown in the Portal UI.
        required: false
        schema:
          type: string
          enum:
          - active
          - scheduled
          - expired
      - in: query
        name: scope
        description: Filter by the level the rule is attached to.
        required: false
        schema:
          type: string
          enum:
          - account
          - organization
          - identity
      - in: query
        name: category
        description: Limit results to a single rule category.
        required: false
        schema:
          type: string
          enum:
          - country
          - vpn
          - ip_address
      - in: query
        name: country_code
        description: Filter by country code value (ISO 3166-1 alpha-2). Implies `category=country`.
        required: false
        schema:
          type: string
      - in: query
        name: vpn
        description: Filter by VPN (tunnel operator) value. Implies `category=vpn`.
        required: false
        schema:
          type: string
      - in: query
        name: ip_address
        description: Filter by IP Address value. Implies `category=ip_address`.
        required: false
        schema:
          type: string
      - 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.

          '
        required: false
        schema:
          type: string
          enum:
          - standard
          - catchall
          - catchall_exception
      responses:
        '200':
          description: List Unwanted Access Rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  unwanted_access_rules:
                    type: array
                    items:
                      $ref: '#/components/schemas/UnwantedAccessRule'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - unwanted_access_rules
                - pagination
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnwantedAccessRule'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.


        **Rule logic.** Provide exactly one of `country_code`, `vpn`, or `logic`:

        - 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.

        - 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.

        - 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`.


        **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.'
      responses:
        '201':
          description: Create an Unwanted Access Rule
          content:
            application/json:
              schema:
                type: object
                properties:
                  unwanted_access_rule:
                    $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnwantedAccessRuleCreationParameters'
        required: true
  /v1/unwanted_access_rules/{id}:
    get:
      summary: Get Unwanted Access Rule
      description: Shows details on a single Unwanted Access Rule associated with your account.
      parameters:
      - in: path
        name: id
        description: Unwanted Access Rule ID.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Get Unwanted Access Rule
          content:
            application/json:
              schema:
                type: object
                properties:
                  unwanted_access_rule:
                    $ref: '#/components/schemas/UnwantedAccessRule'
        '403':
          description: There was an issue with your API credential or permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnwantedAccessRule'
        '404':
          description: Unwanted Access Rule not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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.
      parameters:
      - in: path
        name: id
        description: Unwanted Access Rule ID.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '202':
          description: Unwanted Access Rule deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  unwanted_access_rule:
                    $ref: '#/components/schemas/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.'
      parameters:
      - in: path
        name: id
        description: Unwanted Access Rule ID.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Update an Unwanted Access Rule
          content:
            application/json:
              schema:
                type: object
                properties:
                  unwanted_access_rule:
                    $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnwantedAccessRuleUpdateParameters'
        required: true
components:
  schemas:
    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
    Pagination:
      type: object
      properties:
        next_page_url:
          type: string
        next_page_token:
          type: string
      description: Pagination model
    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
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic