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.
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/global-ip-listsGet global IP blacklist and whitelist
Authentication: Admin only
/api/v2/global-ip-listsSet global IP blacklist and whitelist
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
black | string[] | IP/CIDR of the unexpired blacklist entries. |
black_items | IpListItem[] | Blacklist entries with expiry, reason and source. |
expected_updated_at | string | 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. |
white | string[] | IP/CIDR of the unexpired whitelist entries. |
white_items | IpListItem[] | Whitelist entries with expiry, reason and source. |
/api/v2/global-ip-lists/exportExport global IP list entries
Authentication: 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/global-ip-lists/importBulk import global IP list entries
Authentication: 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 (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. |
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]. |
Global 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[] | IP/CIDR of the unexpired blacklist entries. |
black_items | IpListItem[] | Blacklist entries with expiry, reason and source. |
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 (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. |
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. |
removed | integer | In replace mode, existing entries that are not in the new list (entries with the same IP count as updated, not removed). |
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[] | IP/CIDR of the unexpired whitelist entries. |
white_items | IpListItem[] | 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.
{
"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"
}