Site IP lists site-ip-lists
Permanent IP blacklist and whitelist of one site; blacklisted IPs are dropped and whitelisted IPs skip CC and other protections. The site's temporary whitelist on nodes can also be cleared.
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/site-ip-lists/{site_id}Get site IP blacklist and whitelist
Authentication: User (some parameters admin only)
/api/v2/site-ip-lists/{site_id}Set site IP blacklist and whitelist
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
black | string[] | Permanent blacklist (a match = connection dropped); the count is limited by protect.black_ip_max. |
black_items | IpListItem[] | Blacklist entries with expiry, reason and source; expired entries are not returned. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when the read updated_at is null, i.e. never set, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
white | string[] | Permanent whitelist (a match = CC and other protections are skipped); the count is limited by protect.white_ip_max. |
white_items | IpListItem[] | Whitelist entries with expiry, reason and source; expired entries are not returned. |
/api/v2/site-ip-lists/{site_id}/exportExport site IP list entries
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
listRequired | string | Which list to export. |
source | IpListSource | Only export entries from this source; omit for all. |
format | string | txt (default, one entry per line) or csv (with header, a source column and a UTF-8 BOM). |
/api/v2/site-ip-lists/{site_id}/importBulk import site IP list entries
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
dry_run | boolean | true only checks the file and saves nothing. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when the read updated_at is null, i.e. never set, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
listRequired | string | Which list to import into. |
mode | string | merge adds to the current list (the imported row wins for the same IP); replace swaps the whole list for the imported rows. |
textRequired | string | File content (txt/csv), one entry per line: IP/CIDR[,expiry][,reason]. |
/api/v2/site-ip-lists/{site_id}/ip-detailIP detail
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
ipRequired | string | IPv4 or IPv6 address. |
/api/v2/site-ip-lists/{site_id}/ip-detailBlacklist or whitelist from IP detail
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
expires_at | string | Expiry time; empty = permanent. Must be in the future. |
ipRequired | string | Normalized address (IPv4-mapped addresses shown as IPv4). |
listRequired | string | Which list to import into. |
reason | string | Reason (note), at most 200 characters. |
scopeRequired | string | site = this site's list; global = the global list (admins only). |
/api/v2/site-ip-lists/{site_id}/tmp-white-clearClear site temporary whitelist
Authentication: User (some parameters admin only)
Site IP lists object
| Field | Type | Description |
|---|---|---|
added | integer | Entries added. |
applied | boolean | Whether the import was saved (false for dry_run or when blocking issues exist). |
black | string[] | Permanent blacklist (a match = connection dropped); the count is limited by protect.black_ip_max. |
black_items | IpListItem[] | Blacklist entries with expiry, reason and source; expired entries are not returned. |
block_denied | string | Why it cannot be blacklisted: private (private/loopback/link-local), node (a node IP; admins only), self (the caller's own IP), other (any other reason; tenants get this for node IPs so node addresses are not revealed); omitted when allowed. |
dry_run | boolean | true only checks the file and saves nothing. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when the read updated_at is null, i.e. never set, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
expires_at | string | Expiry time; empty = permanent. Must be in the future. |
geo | GeoipLookup | IP geolocation lookup result. |
global_black | IpListItem | IP list entry (in IP details, the entry that matches the IP; omitted when none matches). |
global_white | IpListItem | IP list entry (in IP details, the entry that matches the IP; omitted when none matches). |
ip | string | Normalized address (IPv4-mapped addresses shown as IPv4). |
issues | IpListImportIssue[] | Per-line issues (at most 1000, ascending by line). |
lines | integer | Number of valid entries (after de-duplication). |
listRequired | string | Which list to import into. |
mode | string | merge adds to the current list (the imported row wins for the same IP); replace swaps the whole list for the imported rows. |
reason | string | Reason (note), at most 200 characters. |
removed | integer | In replace mode, existing entries that are not in the new list (entries with the same IP count as updated, not removed). |
scopeRequired | string | site = this site's list; global = the global list (admins only). |
site_black | IpListItem | IP list entry (in IP details, the entry that matches the IP; omitted when none matches). |
site_id | integer | Site ID |
site_white | IpListItem | IP list entry (in IP details, the entry that matches the IP; omitted when none matches). |
task_id | integer | Id of the background task that pushes the change to nodes (poll progress with GET /tasks/{id}). |
textRequired | string | File content (txt/csv), one entry per line: IP/CIDR[,expiry][,reason]. |
updated | integer | Entries already in the list that were updated by the import. |
updated_at | string | Updated at |
white | string[] | Permanent whitelist (a match = CC and other protections are skipped); the count is limited by protect.white_ip_max. |
white_items | IpListItem[] | Whitelist entries with expiry, reason and source; expired entries are not returned. |
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"
}