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.

ProtectionAuthentication: User (some parameters admin only)8 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.

GET/api/v2/bansList bans

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
ipstring A single address matches exactly; a CIDR returns every ban inside that network (single addresses and networks no shorter than it).
site_idinteger Filter by site.
site_idsstring 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
activeboolean true = only bans that have not expired.
levelstring Filter by scope (global = global blacklist).
Values ["site","tenant","global"]
sourcestring Filter by source: manual = created in the panel; node = banned automatically by a node (challenge limit exceeded, rule ban, handshake flood, etc.).
Values ["manual","node"]
source_typestring 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_fromstring 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.
POST/api/v2/bansCreate ban

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger 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

FieldTypeDescription
expires_atstring Expiry time; null = permanent.
ipRequiredstring IP or CIDR.
levelRequiredstring Scope: site = one site; tenant = all sites of the tenant; global = the whole network (admin only).
Values ["site","tenant","global"]
reasonstring 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_idinteger Site id, required when level=site; 0 otherwise.
GET/api/v2/bans/site-countsCount bans per site

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
source_typestring 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_fromstring 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.
GET/api/v2/bans/source-countsCount bans per source type

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring 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_fromstring 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.
POST/api/v2/bans/unbanUnban by IP

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
allboolean true = unban the whole site, clearing every ban of site_id; level=site only and counts as one unban toward the daily limit.
ipsstring[] 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.
levelRequiredstring Scope: site = one site; tenant = all sites of the tenant; global = the whole network (admin only).
Values ["site","tenant","global"]
site_idinteger Site id, required when level=site; 0 otherwise.
GET/api/v2/bans/unban-quotaUnban quota and today's usage

Authentication: User (some parameters admin only)

GET/api/v2/bans/unbansList unban records

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
site_idinteger Filter by site (site-level unbans only).
site_idsstring 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
sincestring Only records at or after this time (for example to count today's unbans).
by_adminboolean 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).
DELETE/api/v2/bans/{id}Delete ban

Authentication: User (some parameters admin only)

Bans object

FieldTypeDescription
allboolean true = unban the whole site, clearing every ban of site_id; level=site only and counts as one unban toward the daily limit.
batch_maxinteger Maximum IPs per unban request (setting protect.unban_batch_max).
by_adminboolean 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).
countinteger Number of unexpired bans.
created_atstring Created at
read-only
daily_maxinteger Maximum unbans per tenant per day (setting protect.unban_daily_max).
expires_atstring Expiry time; null = permanent.
filter_idstring 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.
read-only
idinteger Record ID
read-only
intelBanIntel 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_hitboolean Whether the IP is in the platform high-risk IP library; null = not judged yet (always null until the library ships).
ipstring IP or CIDR.
ip_countinteger Number of unbanned IPs/CIDRs (0 for a whole-site unban).
ipsstring[] 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.
itemsBanSourceCount[] Items on this page
levelstring Scope: site = one site; tenant = all sites of the tenant; global = the whole network (admin only).
Values ["site","tenant","global"]
reasonstring 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.
removedinteger Number of entries removed from the ban table at the same time.
rule_idstring 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.
read-only
site_idinteger Site id, required when level=site; 0 otherwise.
sourcestring 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.
read-onlyValues ["manual","node"]
source_typeBanSourceType 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.
Values ["manual","cc","waf","scan","status","tls","intel"]
statusstring Status of the push task pending/running/done/failed; null once the task has been purged.
task_idinteger Id of the background task that pushes the change to nodes (poll progress with GET /tasks/{id}).
tenant_idinteger Owning tenant; null = platform object (built-in or created by an admin, read-only for tenants).
read-only
updated_atstring Updated at
read-only
usedinteger 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.

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