Version 2.4.8 · latest

Global IP lists global-ip-lists

Platform-wide IP blacklist and whitelist with optional expiry, reason and source per entry, plus bulk import and export; admin only.

Pick an endpoint to see its example call on the right.

ProtectionAuthentication: Admin only4 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.

PUT/api/v2/global-ip-listsSet global IP blacklist and whitelist

Authentication: Admin only

Request body application/json

FieldTypeDescription
blackstring[] IP/CIDR of the unexpired blacklist entries.
black_itemsIpListItem[] Blacklist entries with expiry, reason and source.
expected_updated_atstring Optimistic lock - the updated_at as the caller read it (use 1970-01-01T00:00:00Z when it was null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
whitestring[] IP/CIDR of the unexpired whitelist entries.
white_itemsIpListItem[] Whitelist entries with expiry, reason and source.
GET/api/v2/global-ip-lists/exportExport global IP list entries

Authentication: 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/global-ip-lists/importBulk import global IP list entries

Authentication: 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 (use 1970-01-01T00:00:00Z when it was null). 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].

Global IP lists object

FieldTypeDescription
addedinteger Entries added.
appliedboolean Whether the import was saved (false for dry_run or when blocking issues exist).
blackstring[] IP/CIDR of the unexpired blacklist entries.
black_itemsIpListItem[] Blacklist entries with expiry, reason and source.
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 (use 1970-01-01T00:00:00Z when it was null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check.
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"
removedinteger In replace mode, existing entries that are not in the new list (entries with the same IP count as updated, not removed).
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[] IP/CIDR of the unexpired whitelist entries.
white_itemsIpListItem[] Whitelist entries with expiry, reason and source.

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