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.
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.
/api/v2/guard-blacklistsList region/node firewall blacklists
Authentication: Admin only
/api/v2/guard-blacklists/{scope}/{scope_id}Download a region/node firewall blacklist
Authentication: Admin only
/api/v2/guard-blacklists/{scope}/{scope_id}Import a region/node firewall blacklist
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
allow_broad | boolean | 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. |
/api/v2/guard-blacklists/{scope}/{scope_id}Delete a region/node firewall blacklist
Authentication: Admin only
Region/node blacklists object
| Field | Type | Description |
|---|---|---|
entries | integer | Number of entries after deduplication. |
items | GuardBlacklist[] | Items on this page |
limit | integer | Maximum number of entries per list. |
name | string | Region name or main node name (empty if the node is unnamed). |
scope | string | Tier the list belongs to: region = region tier; node = node tier (replaces the region tier list entirely). |
scope_id | integer | Region ID or main node ID. |
sha256 | string | sha256 of the normalized text (nodes fetch by it). |
size | integer | Size of the normalized text in bytes. |
updated_at | string | 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.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"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"
}