High-risk IP library intel
The platform-provided high-risk IP library (paid item rules update, synced hourly): status, platform-wide handling policy, entry lookup, whitelisting a single entry and today's visits that hit it; read-only for tenants.
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/intelGet high-risk IP library status
Authentication: User (some parameters admin only)
/api/v2/intel/allowWhitelist a high-risk IP
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
ipRequired | string | Address or network. |
reason | string | Why it is whitelisted (kept on the whitelist entry); defaults to a fixed note when omitted. |
/api/v2/intel/ipsList high-risk IP library entries
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
ip | string | A single address returns the entry covering it; anything else filters by substring of the CIDR text (admins only; tenants must give a single address). |
level | IntelLevel | Filter by level. |
reason | IntelReason | Filter by type. |
/api/v2/intel/policyUpdate high-risk IP library policy
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
actionRequired | IntelAction | Handling: challenge (pass only after a JS check), block (ban on the site and answer 403), log (record only). |
levelRequired | IntelLevel | Level: high (exploit type or score >= 80); medium. |
/api/v2/intel/suspectsList suspicious IP report status
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
status | IntelSuspectStatus | Filter by status; omit for all. |
ip | string | Only these addresses (comma-separated, at most 200), for labelling IPs in lists such as bans; invalid addresses are ignored. |
/api/v2/intel/suspectsReport suspicious IPs
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
ipsRequired | string[] | Single IP addresses (no networks). |
reason | string | Why it is whitelisted (kept on the whitelist entry); defaults to a fixed note when omitted. |
/api/v2/intel/visitorsHigh-risk IPs that visited today
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
site_id | integer | Filter by site. |
High-risk IP library object
| Field | Type | Description |
|---|---|---|
actionRequired | IntelAction | Handling: challenge (pass only after a JS check), block (ban on the site and answer 403), log (record only). |
actions | IntelAction[] | Handling applied to it today. |
added_at | string | When the entry was added (kept when the same IP is written again). |
cidr | string | Address or network (canonical form). |
count | integer | Number of entries. |
entry | IntelEntry | One entry of the high-risk IP library. |
error | string | Why the latest sync failed (the version in use is kept); empty on success. |
expires_at | string | Expiry time; empty = permanent. An expired entry stops matching by itself (nodes judge by their own clock, independent of the master); the master then removes it and the next config push carries the removal. Must be in the future when written. |
first_seen_at | string | When it first entered the library; absent when the library does not say. |
generated_at | string | When the library was generated (on the super admin side). |
halt | string | Why updates are halted by the license (expired, disabled, or the super admin unreachable for long) (admins only; not a failure, separate from error; absent when not halted). |
high | integer | Number of high-risk entries. |
hits | integer | Times blocked in the 24 hours before the report. |
ipRequired | string | Address or network. |
ipsRequired | string[] | Single IP addresses (no networks). |
items | IntelSuspectResult[] | Items on this page |
last_at | string | Time of the latest hit. |
level | IntelLevel | Level: high (exploit type or score >= 80); medium. |
masters | integer | Number of controllers that reported it within 24 hours; absent when the library does not say. |
medium | integer | Number of medium-risk entries. |
mode | IntelSuspectMode | How it was reported: auto (automatic conditions) or manual (by an admin or a manual ban). |
policy | IntelPolicy | Platform-wide policy of the high-risk IP library; the site config field intel.action can override or turn it off. |
queued | integer | Number of entries queued. |
reason | string | Why it is whitelisted (kept on the whitelist entry); defaults to a fixed note when omitted. |
reported_at | string | When it was last reported. |
score | integer | Risk score (1-100). |
serving | boolean | Whether a library is being pushed to nodes (fetched at least once and not expired). |
sites | integer | Number of sites involved. |
source | IpListSource | Where the entry came from: manual (added by hand), import (bulk import), ip_detail (blacklisted/whitelisted from the IP detail page), api (written through the API). |
stale | boolean | The license no longer carries the library and the last version is over 24 hours old, so it is no longer served. |
status | IntelSuspectStatus | Suspicious IP status: queued (not sent yet), pending (reported, awaiting review), admitted (added to the high-risk IP library), ignored. |
status_at | string | When the status last changed; null before it is sent. |
sub | string | Sub-type (for example WAF consecutive hits); absent when the library does not say. |
synced_at | string | Time of the latest sync. |
version | string | Version of the library being served; empty if none. |
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"
}