Version 2.4.8 · latest

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.

ProtectionAuthentication: User (some parameters admin only)7 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/site-ip-lists/{site_id}Get site IP blacklist and whitelist

Authentication: User (some parameters admin only)

PUT/api/v2/site-ip-lists/{site_id}Set site IP blacklist and whitelist

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
blackstring[] Permanent blacklist (a match = connection dropped); the count is limited by protect.black_ip_max.
black_itemsIpListItem[] Blacklist entries with expiry, reason and source; expired entries are not returned.
expected_updated_atstring 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.
whitestring[] Permanent whitelist (a match = CC and other protections are skipped); the count is limited by protect.white_ip_max.
white_itemsIpListItem[] Whitelist entries with expiry, reason and source; expired entries are not returned.
GET/api/v2/site-ip-lists/{site_id}/exportExport site IP list entries

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
listRequiredstring Which list to export.
Values ["black","white"]
sourceIpListSource Only export entries from this source; omit for all.
Values ["manual","import","ip_detail","api"]
formatstring txt (default, one entry per line) or csv (with header, a source column and a UTF-8 BOM).
Values ["txt","csv"]Default "txt"
POST/api/v2/site-ip-lists/{site_id}/importBulk import site IP list entries

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
dry_runboolean true only checks the file and saves nothing.
Default false
expected_updated_atstring 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.
listRequiredstring Which list to import into.
Values ["black","white"]
modestring merge adds to the current list (the imported row wins for the same IP); replace swaps the whole list for the imported rows.
Values ["merge","replace"]Default "merge"
textRequiredstring File content (txt/csv), one entry per line: IP/CIDR[,expiry][,reason].
GET/api/v2/site-ip-lists/{site_id}/ip-detailIP detail

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
ipRequiredstring IPv4 or IPv6 address.
POST/api/v2/site-ip-lists/{site_id}/ip-detailBlacklist or whitelist from IP detail

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
expires_atstring Expiry time; empty = permanent. Must be in the future.
ipRequiredstring Normalized address (IPv4-mapped addresses shown as IPv4).
listRequiredstring Which list to import into.
Values ["black","white"]
reasonstring Reason (note), at most 200 characters.
scopeRequiredstring site = this site's list; global = the global list (admins only).
Values ["site","global"]
POST/api/v2/site-ip-lists/{site_id}/tmp-white-clearClear site temporary whitelist

Authentication: User (some parameters admin only)

Site IP lists object

FieldTypeDescription
addedinteger Entries added.
appliedboolean Whether the import was saved (false for dry_run or when blocking issues exist).
blackstring[] Permanent blacklist (a match = connection dropped); the count is limited by protect.black_ip_max.
black_itemsIpListItem[] Blacklist entries with expiry, reason and source; expired entries are not returned.
block_deniedstring 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.
Values ["private","node","self","other"]
dry_runboolean true only checks the file and saves nothing.
Default false
expected_updated_atstring 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_atstring Expiry time; empty = permanent. Must be in the future.
geoGeoipLookup IP geolocation lookup result.
global_blackIpListItem IP list entry (in IP details, the entry that matches the IP; omitted when none matches).
global_whiteIpListItem IP list entry (in IP details, the entry that matches the IP; omitted when none matches).
ipstring Normalized address (IPv4-mapped addresses shown as IPv4).
issuesIpListImportIssue[] Per-line issues (at most 1000, ascending by line).
linesinteger Number of valid entries (after de-duplication).
listRequiredstring Which list to import into.
Values ["black","white"]
modestring merge adds to the current list (the imported row wins for the same IP); replace swaps the whole list for the imported rows.
Values ["merge","replace"]Default "merge"
reasonstring Reason (note), at most 200 characters.
removedinteger In replace mode, existing entries that are not in the new list (entries with the same IP count as updated, not removed).
scopeRequiredstring site = this site's list; global = the global list (admins only).
Values ["site","global"]
site_blackIpListItem IP list entry (in IP details, the entry that matches the IP; omitted when none matches).
site_idinteger Site ID
read-only
site_whiteIpListItem IP list entry (in IP details, the entry that matches the IP; omitted when none matches).
task_idinteger Id of the background task that pushes the change to nodes (poll progress with GET /tasks/{id}).
textRequiredstring File content (txt/csv), one entry per line: IP/CIDR[,expiry][,reason].
updatedinteger Entries already in the list that were updated by the import.
updated_atstring Updated at
read-only
whitestring[] Permanent whitelist (a match = CC and other protections are skipped); the count is limited by protect.white_ip_max.
white_itemsIpListItem[] 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.

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