Version 2.4.8 · latest

Region/node blacklists guard-blacklists

Firewall blacklist files imported per region or main node (up to 1,000,000 entries each), delivered to nodes as separate files instead of the global snapshot.

Pick an endpoint to see its example call on the right.

Operations and systemAuthentication: Admin only4 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

PUT/api/v2/guard-blacklists/{scope}/{scope_id}Import a region/node firewall blacklist

Authentication: Admin only

Query parameters

FieldTypeDescription
allow_broadboolean When true, accepts overly broad prefixes (IPv4 shorter than /8, IPv6 shorter than /16); omitted or false rejects them with 422 broad_prefix, and the panel resends with true after confirmation.

Region/node blacklists object

FieldTypeDescription
entriesinteger Number of entries after deduplication.
itemsGuardBlacklist[] Items on this page
limitinteger Maximum number of entries per list.
namestring Region name or main node name (empty if the node is unnamed).
scopestring Tier the list belongs to: region = region tier; node = node tier (replaces the region tier list entirely).
Values ["region","node"]
scope_idinteger Region ID or main node ID.
sha256string sha256 of the normalized text (nodes fetch by it).
sizeinteger Size of the normalized text in bytes.
updated_atstring Import time.

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command