Bans bans
Records of blocked IPs: bans created by hand, unban by IP or for a whole site with an unban history, and automatic bans reported by nodes.
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/bansList bans
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
ip | string | A single address matches exactly; a CIDR returns every ban inside that network (single addresses and networks no shorter than it). |
site_id | integer | Filter by site. |
site_ids | string | Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection |
active | boolean | true = only bans that have not expired. |
level | string | Filter by scope (global = global blacklist). |
source | string | Filter by source: manual = created in the panel; node = banned automatically by a node (challenge limit exceeded, rule ban, handshake flood, etc.). |
source_type | string | Filter by source type (manual / cc / waf / scan / status / tls / intel). Accepts a comma-separated list (e.g. status,tls; duplicates are dropped); every item must be one of the seven values, otherwise 422. Omit for all. |
created_from | string | Only bans created at or after this instant (e.g. "added today"). A repeat ban by a node extends the existing row and does not change its creation time, so only the first record counts. |
/api/v2/bansCreate ban
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: tenant the ban belongs to. Required for level=tenant; optional for level=site (defaults to the site owner, and must match it when given). Ignored for tenant credentials |
Request body application/json
| Field | Type | Description |
|---|---|---|
expires_at | string | Expiry time; null = permanent. |
ipRequired | string | IP or CIDR. |
levelRequired | string | Scope: site = one site; tenant = all sites of the tenant; global = the whole network (admin only). |
reason | string | Reason: manual by default for bans created in the panel; for automatic bans by a node, the triggering rule (ruleset/rule id such as cc.level.r5/r1) or module name (ssl_handshake = handshake flood), or auto when there is no rule. |
site_id | integer | Site id, required when level=site; 0 otherwise. |
/api/v2/bans/site-countsCount bans per site
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
source_type | string | Filter by source type (manual / cc / waf / scan / status / tls / intel). Accepts a comma-separated list (e.g. status,tls; duplicates are dropped); every item must be one of the seven values, otherwise 422. Omit for all. |
created_from | string | Only bans created at or after this instant (e.g. "added today"). A repeat ban by a node extends the existing row and does not change its creation time, so only the first record counts. |
/api/v2/bans/source-countsCount bans per source type
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
created_from | string | Only bans created at or after this instant (e.g. "added today"). A repeat ban by a node extends the existing row and does not change its creation time, so only the first record counts. |
/api/v2/bans/unbanUnban by IP
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
all | boolean | true = unban the whole site, clearing every ban of site_id; level=site only and counts as one unban toward the daily limit. |
ips | string[] | IPs/CIDRs to unban (omit when all=true, required otherwise); the number per request is limited by protect.unban_batch_max and the daily count per tenant by protect.unban_daily_max. |
levelRequired | string | Scope: site = one site; tenant = all sites of the tenant; global = the whole network (admin only). |
site_id | integer | Site id, required when level=site; 0 otherwise. |
/api/v2/bans/unban-quotaUnban quota and today's usage
Authentication: User (some parameters admin only)
/api/v2/bans/unbansList unban records
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
site_id | integer | Filter by site (site-level unbans only). |
site_ids | string | Filter by sites: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection |
since | string | Only records at or after this time (for example to count today's unbans). |
by_admin | boolean | Filter by whether an administrator unbanned on the site owner's behalf; pass false to count the owner's own unbans today (those done by an administrator do not use the owner's quota). |
/api/v2/bans/{id}Delete ban
Authentication: User (some parameters admin only)
Bans object
| Field | Type | Description |
|---|---|---|
all | boolean | true = unban the whole site, clearing every ban of site_id; level=site only and counts as one unban toward the daily limit. |
batch_max | integer | Maximum IPs per unban request (setting protect.unban_batch_max). |
by_admin | boolean | true = unbanned by an administrator on the site owner's behalf (recorded under and visible to the owner, does not use the owner's daily quota). |
count | integer | Number of unexpired bans. |
created_at | string | Created at |
daily_max | integer | Maximum unbans per tenant per day (setting protect.unban_daily_max). |
expires_at | string | Expiry time; null = permanent. |
filter_id | string | The filter (rule set or module) that triggered the ban, split from reason, such as cc.level.r5, waf, scan.builtin or ssl_handshake; absent for manual bans and for auto. |
id | integer | Record ID |
intel | BanIntel | Where a banned IP stands in the platform high-risk IP library right now (looked up against the current library when listing; fields the library does not carry, or entries already expired, are absent). |
intel_hit | boolean | Whether the IP is in the platform high-risk IP library; null = not judged yet (always null until the library ships). |
ip | string | IP or CIDR. |
ip_count | integer | Number of unbanned IPs/CIDRs (0 for a whole-site unban). |
ips | string[] | IPs/CIDRs to unban (omit when all=true, required otherwise); the number per request is limited by protect.unban_batch_max and the daily count per tenant by protect.unban_daily_max. |
items | BanSourceCount[] | Items on this page |
level | string | Scope: site = one site; tenant = all sites of the tenant; global = the whole network (admin only). |
reason | string | Reason: manual by default for bans created in the panel; for automatic bans by a node, the triggering rule (ruleset/rule id such as cc.level.r5/r1) or module name (ssl_handshake = handshake flood), or auto when there is no rule. |
removed | integer | Number of entries removed from the ban table at the same time. |
rule_id | string | The rule number that triggered the ban, split from reason (r1 of cc.level.r5/r1, 941100 of waf:941100); absent when there is none. |
site_id | integer | Site id, required when level=site; 0 otherwise. |
source | string | manual = created in the panel; node = banned automatically by a node and reported (one row per target while unexpired; a repeat ban extends it). Both are lifted the same way, by deleting or via /bans/unban. |
source_type | BanSourceType | Source type: manual = created in the panel; cc = CC rule group (cc.level.*, cc.user.*, auto and other rule sets); waf = repeated WAF rule hits; scan = built-in scanner set; status = built-in status-code set; tls = handshake flood; intel = platform high-risk IP library. A ban made by a node is never manual. |
status | string | Status of the push task pending/running/done/failed; null once the task has been purged. |
task_id | integer | Id of the background task that pushes the change to nodes (poll progress with GET /tasks/{id}). |
tenant_id | integer | Owning tenant; null = platform object (built-in or created by an admin, read-only for tenants). |
updated_at | string | Updated at |
used | integer | Unbans the tenant made itself today (since 00:00 UTC); unbans by an administrator do not count, and it is 0 when an administrator calls. |
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"
}