Operate the DDoS protection service for all customers: protection policy, attacks, mitigation approvals, upstream mitigation, tunnels and BGP, integrations, reports, customers and usage. Requests are authenticated with an API token created in the MSSP console.
Base URL: https://mssp.example.com:8443
Getting started
The API is a JSON-over-HTTPS REST API. It is the same API the MSSP console uses: everything you can do in the console for all customers can be automated.
Create a token. Sign in to the MSSP console, open the user menu (top right) and choose API tokens. Give it a name, optionally make it read-only and restrict it to your source networks, then copy the token. It is shown only once.
Call the API with the token in the Authorization header:
Request and response bodies are JSON (Content-Type: application/json); request bodies are limited to 64 KiB and unknown fields are rejected.
Times are RFC 3339 in UTC (2026-10-15T12:00:00Z). Rates are packets per second (pps) and bits per second (bps).
Prefixes have a numeric id; attacks (incidents) have an id of the form <prefix_id>-<start_unix>.
Many configuration changes accept ?dry_run=true: the request is fully validated and the result is returned, but nothing is applied.
Every change is written to the appliance's tamper-evident audit log with the token's user name.
Authentication
Send an API token as a Bearer token on every request:
Authorization: Bearer wsk_1a2b3c4d_…
A token acts as the user who created it and has exactly that user's permissions (operator: read and change; viewer: read only).
Token options
Lifetime
1 hour to 365 days (default 90 days). Expired tokens stop working; create a new one before expiry.
Read-only
The token can only read. Any change returns 403. Recommended for dashboards, SIEM pulls and monitoring.
Allowed networks
Up to 16 CIDRs. Requests from other source addresses are rejected with 401. The address checked is your client's public address as seen by the portal.
Each user can have at most 20 tokens. The panel shows when each token was last used; revoke tokens you no longer use.
Tokens stop working immediately when they are revoked, when the user is suspended or deleted, or when the user's password is reset. Tokens cannot create other tokens.
Treat a token like a password: store it in a secret manager, never in source code or URLs.
Errors & limits
Errors return a JSON body with an error message. Validation errors (422) also list every problem:
{
"error": "invalid settings",
"problems": ["invalid e-mail address: noc@", "choose at least one event"]
}
Status
Meaning
400
Malformed request (invalid JSON, unknown field, bad parameter).
401
Missing, invalid, expired or revoked token, or a source address outside the token's allowed networks.
403
The user lacks the permission, or a read-only token was used for a change.
404
Not found.
409
Conflict with the current state (for example a limit is reached or the resource is in use).
422
Validation failed; see problems.
429
Rate limited; retry after the number of seconds in Retry-After.
501
The feature is not enabled on this deployment.
503
Temporarily unavailable (for a change: the audit record could not be written, so nothing was changed).
Rate limits
Each user may send up to 20 requests per second (bursts up to 40), shared by all of the user's tokens; each client address up to 60 per second. Use the live event stream instead of polling quickly for changes.
Live events (SSE)
GET /v1/events is a Server-Sent Events stream. Keep it open to react to attacks within a second instead of polling.
Packet capture, self-protection, flow export and license changes.
Reconnecting
Reconnect with the last received id in the Last-Event-ID header (or ?last_event_id=); the last 1000 events are replayed.
event: reset means events were missed and cannot be replayed: re-read the state (for example GET /v1/incidents).
event: overflow closes a consumer that reads too slowly; event: unauthorized ends the stream when the token is revoked or expires.
A : ping comment is sent every 15 seconds. At most 5 streams can be open per user.
Python example:
import json, requests
r = requests.get("https://mssp.example.com:8443/v1/events", headers={"Authorization": "Bearer " + TOKEN}, stream=True, timeout=(10, 60))
event = None
for line in r.iter_lines(decode_unicode=True):
if line.startswith("event:"):
event = line[6:].strip()
elif line.startswith("data:") and event == "attack.start":
ev = json.loads(line[5:])
print("attack on", ev["data"]["prefix"], ev["data"]["vector"])
Webhooks
Webhook channels (Integrations) POST a JSON document to your URL for every event selected by a notification rule. Channels and rules are managed with the Integrations endpoints or in the console.
severity is one of info, notice, warning, high, critical. fields values are strings. The document format is stable; new fields may be added.
Verifying the signature
When the channel has a secret, the signature is hex(HMAC-SHA256(secret, timestamp + "." + raw_body)). Verify it on the raw request body and reject old timestamps to prevent replays:
Any 2xx response is success. Other responses and timeouts (15 s) are retried after 1 s, 5 s, 30 s, 2 min and 10 min, then dropped and shown in the delivery history.
Each channel sends at most 60 messages per minute; HTTPS is required unless the channel explicitly allows plain HTTP.
The slack format sends {"text": "title\nbody"} for Slack-compatible incoming webhooks instead of the document above.
Customer-scoped channels only receive that customer's attack, mode and report events.
Syslog & CEF
Syslog channels send RFC 5424 messages over UDP, TCP or TLS. The message body is either ArcSight CEF (default) or the same JSON document as webhooks.
Event type with _ (attack_start, attack_end, prefix_mode, system_alert, …)
Severity
1 info, 3 notice, 5 warning, 8 high, 10 critical
rt, externalId, msg
Event time (ms), event id, title
cs1–cs5
vector, prefix, tenant, action, by (user who made the change)
cn1–cn3
peakPps, peakBps, durationSeconds (attack end)
The syslog facility (default local0) and application name (default wireshield) are configurable per channel. For TLS, a private CA can be set on the channel.
Prometheus metrics
GET /metrics serves Prometheus text format with data-plane counters, per-prefix rates, attack state, notification delivery counters and appliance health. Use a read-only token restricted to your Prometheus server's address:
Traffic time series of the attack: 10 s buckets (incoming / dropped pps and bit/s; including 5 min before and after the attack, downsampled for very long attacks), vector (traffic class) composition within the attack window and peak rate/total per countermeasure (drop reason) (estimated from sampling). Used by the PDF attack report and the chart
permission: incident:readread-only users
Parameters
Name
In
Type
Description
idrequired
path
string
<prefix_id>-<start_unix>
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Attack or series record not found (for a tenant, another tenant's incident also returns 404)
429
Rate limited
501
Attack records or series recording are not configured
Manually terminate an ongoing attack: the prefix is switched to SENSOR and new detection is held off for 120 s (management roles only). Optional body: relearn: true → the traffic was normal, the learned baseline is set to the current level (the same level will not open a new incident)
Overall protocol breakdown time series (packets/s; TCP, UDP, ICMP+ICMPv6, other). From the data plane's real counters (not sampling). res: 10s (last 1 hour, default) | 1m (last 24 hours); from/to RFC3339. Kept in memory: starts empty when the service restarts
permission: global:readread-only users
Parameters
Name
In
Type
Description
res
query
string
10s | 1m
from
query
string
RFC3339
to
query
string
RFC3339
Responses
200
Success
400
Invalid resolution or range
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Dimension breakdown time series of overall traffic (Traffic Analyzer): dim = country | asn | protocol | port | target; metric = bps (default) | pps; res = 10s (last 1 hour) | 1m (last 24 hours); n = at most 10 keys (default 8). keys are sorted by their total over the range, values are aligned with them, other is the sum of the remaining keys. Estimated from sampling; kept in memory (cleared when the service restarts)
permission: global:readread-only users
Parameters
Name
In
Type
Description
dim
query
string
metric
query
string
res
query
string
from
query
string
to
query
string
n
query
integer
Responses
200
Success
400
Invalid dimension/metric/resolution/range
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Start a time-limited PCAP capture for a prefix: XDP copies the first snaplen bytes of each packet (including payload!) to a second ring; the verdict is not affected. The duration is also enforced in the data plane (it ends even if the service dies). One capture per prefix, at most 8 concurrent; file at most 256 MiB; max_pps is the total packets/s limit. The filter (src/dst/proto/sport/dport) is applied to the captured bytes. An audit record is written
Capture file: classic libpcap (nanosecond, Ethernet); opens in tcpdump/Wireshark. Finished captures only. Every download is written to the audit chain (if it cannot be written, the download is refused)
permission: capture:readaudited
Parameters
Name
In
Type
Description
idrequired
path
string
capture ID (cap-<prefix_id>-<unix_ms>)
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Capture not found
409
Capture is running
429
Rate limited
501
PCAP capture is disabled
503
Audit record could not be written (operation not performed)
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/captures/{id}/stop"
GET/v1/export
IPFIX / sFlow export: configured collectors and their status (records/messages/bytes sent, queue drops, errors, last send, IPFIX active flow count). The data source is XDP samples (telemetry.sample_rate); IPFIX counters are ESTIMATES scaled by the sampling weight
permission: export:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Flow summary of the attack archive: 5-tuple + weighted (estimated) packets/bytes per verdict, top N by packet count descending. distinct_sources is the number of unique sources; truncated indicates new keys were not counted because of too many distinct flows
permission: incident:readread-only users
Parameters
Name
In
Type
Description
idrequired
path
string
<prefix_id>-<start_unix>
src
query
string
source IP or CIDR (sources may be spoofed)
dst
query
string
destination IP or CIDR
sport
query
integer
source port
dport
query
integer
destination port
proto
query
string
tcp | udp | icmp | icmpv6 | gre | esp | sctp or 0-255
verdict
query
string
pass | drop | would_drop | challenge
reason
query
string
drop reason (e.g. rate, rule, blocklist)
n
query
integer
maximum flows (default 50, max 1000)
Responses
200
Success
400
Invalid filter/parameter
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Attack or its archive not found (for a tenant, another tenant's attack also returns 404)
Raw sample archive of the attack: packet headers sampled by XDP (from 60 s before the attack to 60 s after; no payload). Each record is one sampled packet (w = number of packets it represents); samples above 2000 records per second are merged by weight (n = number of merged samples). During an active attack the archive is read with ~1 s delay (archive.closed=false); it is closed and compressed 60 s after the attack ends
permission: incident:readread-only users
Parameters
Name
In
Type
Description
idrequired
path
string
<prefix_id>-<start_unix>
src
query
string
source IP or CIDR (sources may be spoofed)
dst
query
string
destination IP or CIDR
sport
query
integer
source port
dport
query
integer
destination port
proto
query
string
tcp | udp | icmp | icmpv6 | gre | esp | sctp or 0-255
verdict
query
string
pass | drop | would_drop | challenge
reason
query
string
drop reason (e.g. rate, rule, blocklist)
limit
query
integer
page size (default 100, max 1000)
offset
query
integer
`next_offset` from the previous response
Responses
200
Success
400
Invalid filter/parameter
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Attack or its archive not found (for a tenant, another tenant's attack also returns 404)
RULE SUGGESTIONS: clusters the attack samples (verdict ≠ pass) from the attack's sample archive and derives the narrowest rules (proto, port, TCP flags, length, TTL, source country/ASN); measures each rule's side effect against the passed (pass) traffic in the SAME archive and ranks them by greedy coverage. Fully deterministic and on-device (no external service/AI). Rules are always produced as count (observe) and validated with the appliance's own compiler; NONE are applied automatically. Admin/operator only (tenants and viewers cannot see it); samples are header-level (no payload content)
permission: incident:write
Parameters
Name
In
Type
Description
idrequired
path
string
<prefix_id>-<start_unix>
max
query
integer
maximum suggestions (default 5, max 20)
min_samples
query
integer
minimum raw sample count for a cluster (default 30)
min_coverage
query
number
minimum fraction of attack weight (0-1], default 0.05
Responses
200
Success
400
Invalid filter/parameter
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Attack or its archive not found (for a tenant, another tenant's attack also returns 404)
Server-Sent Events stream for attack and state changes.
GET/v1/events
Live event stream (Server-Sent Events). Events: attack.start, attack.end, prefix.mode, protection.changed, incident.note. Each event's id is monotonic and stays greater than previous ones across restarts; with Last-Event-ID (header or last_event_id) the last 1000 events are replayed, and if the events in between are no longer kept, event: reset is sent (re-read the state). A slow consumer is closed with event: overflow. A : ping every 15 s; the stream ends with event: unauthorized if the session/account/token becomes invalid. A tenant sees only attack/mode events for its own prefixes (no protection or note events). Events are notifications only: the source of truth is the event file and the state stores.
The customer's own e-mail notification settings: recipients, selected events (attack started/ended, report ready, prefix mode changed) and language. available=false when the provider has not offered an e-mail channel to customers. SMTP settings are never shown
permission: prefix:readread-only users
Parameters
Name
In
Type
Description
tenant
query
string
staff only: which customer (a customer sees its own; another customer's returns 404)
Responses
200
Success
400
The tenant parameter is required for staff
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Saves the customer's own e-mail notification settings (at most 10 recipients; only customer events can be selected; system/operator events are never sent to customers). Mail is sent through the e-mail channel the provider marked as open to customers; no recipients = the customer's channel and rule are removed. Audited (addresses are not written to the audit log)
permission: mynotify:writeaudited
Parameters
Name
In
Type
Description
tenant
query
string
staff only: which customer (a customer sees its own; another customer's returns 404)
Sends a test e-mail to the customer's recipients (once a minute per customer). Error details are not returned to the customer; staff see them in the delivery history
permission: mynotify:writeaudited
Parameters
Name
In
Type
Description
tenant
query
string
staff only: which customer (a customer sees its own; another customer's returns 404)
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
409
No enabled settings saved yet
429
Wait a minute between tests
501
Notifications are not configured
503
Audit record could not be written (operation not performed)
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/my/notifications/test"
GET/v1/my/protection
READ-ONLY, threshold-free summary of the protection applied to the customer's own prefixes: prefixes and operating mode, groups, protection features (SYN authentication, amplification filter, etc.), rules (name, action, readable match summary, packet/drop counts) and the rate limits in use. Detection thresholds and other customers' information are NOT included
permission: prefix:readread-only users
Parameters
Name
In
Type
Description
tenant
query
string
staff only: which customer (a customer sees its own; another customer's returns 404)
Responses
200
Success
400
The tenant parameter is required for staff
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Customer not found (another customer's also returns 404)
Learned normal-traffic baselines used for detection.
GET/v1/prefixes/{id}/learning
Learning/monitor mode: while the prefix is in mode: learning no packets are dropped; detection and policies run but no action is applied ('would have' records appear in the attack list with action=learning). This endpoint returns the per-class pps/bit-s distribution (p50/p95/p99/peak) learned from NON-ATTACK (normal) traffic, the current static threshold in the profile and the suggested threshold (suggestion = max(p99×2, peak×1.25), floor 1000 pps / 10 Mbit/s, rounded up to two significant digits). ready becomes true after at least 6 hours of normal traffic are observed. The suggestion is informational: it is applied to the profile manually (with preview); suggested_thresholds_json is in the profile's detection.thresholds format
permission: prefix:readread-only users
Parameters
Name
In
Type
Description
idrequired
path
integer
prefix ID
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Prefix not found (for a tenant, another tenant's prefix also returns 404)
Delete the learned distribution (new learning period). Permission: mode change (management roles; a tenant only for its own prefix and if allowed)
permission: mode:setaudited
Parameters
Name
In
Type
Description
idrequired
path
integer
prefix ID
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Prefix not found (for a tenant, another tenant's prefix also returns 404)
429
Rate limited
501
Learning data is disabled
503
Audit record could not be written (operation not performed)
Response example map of any
{
"key": null
}
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/prefixes/{id}/learning/reset"
Allow & deny lists
Per-prefix source allow/deny lists.
GET/v1/prefixes/{id}/lists
The prefix's customer allow/deny lists. A tenant sees ONLY its own prefix (another tenant's returns 404); the username of the user who added an entry is not shown to the tenant. limit: per-list quota for this identity, can_edit: write permission
permission: prefixlist:readread-only users
Parameters
Name
In
Type
Description
idrequired
path
integer
protected prefix ID
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Add an entry to the list (single IP or CIDR; v4 ≥ /8, v6 ≥ /32; loopback/multicast/link-local/reserved ranges are rejected). Order: global allow > global deny > prefix allow > prefix deny > …; a customer allow bypasses all remaining filters but cannot override the operator's global deny. A tenant needs the can_edit_lists policy and the list_limit quota
The prefix's custom rules (in priority order) and their counters. A tenant sees only its own prefix; the username of the rule author is not shown to the tenant
permission: prefixlist:readread-only users
Parameters
Name
In
Type
Description
idrequired
path
integer
protected prefix ID
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Add a custom rule. Order: global allow/deny > customer allow/deny lists > malformed packets > custom rules (by priority, first match wins) > profile. when=always: an Automatic prefix applies it even when there is no attack; attack: only while filters are engaged. In Monitor/Learning no rule drops (counted as wd); in Bypass rules are not evaluated. action=limit is the rule's own limit (pps/bps, scope prefix|dst|src). A tenant needs can_edit_rules and rule_limit; a tenant's allow rule requires a specific source (v4 ≥ /16, v6 ≥ /48)
Replace a custom rule (all fields; ID and creation time are kept). Counters are reset when the content changes, and kept when only the priority changes
Protection groups, profiles, rules and rate limiters.
PATCH/v1/prefixes/{id}
Change a managed prefix's profile/group/configured mode assignment (409 for static). Does not create a version; no ETag precondition. If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
integer
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Protection configuration summary: version/ETag, static and managed record counts, compile warnings. The response ETag header is the current protection version.
permission: protection:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Protection groups: prefix count, tenants, modes, active attacks (unnamed groups referenced only by prefixes are implicit). The response ETag header is the current protection version.
permission: protection:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Create a group (id is assigned if not given). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Delete a group (prefixes keep using the group ID; only the name is lost). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
integer
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Responses
200
Success
400
Invalid request
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Not found
409
Static record (cannot be changed), already exists or in use (`used_by`)
412
If-Match does not match the current version (`current_etag`)
Replace a managed limiter (the name cannot be changed). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
namerequired
path
string
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Delete a managed limiter (409 if rules use it). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
namerequired
path
string
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Responses
200
Success
400
Invalid request
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Not found
409
Static record (cannot be changed), already exists or in use (`used_by`)
412
If-Match does not match the current version (`current_etag`)
Add an entry to an allow/deny list. The lists are GLOBAL: they affect all prefixes. If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
kindrequired
path
string (allow | deny)
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Remove a managed entry from the list (409 for static). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
kindrequired
path
string (allow | deny)
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
cidr
query
string
entry to delete
Responses
200
Success
400
Invalid request
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Not found
409
Static record (cannot be changed), already exists or in use (`used_by`)
412
If-Match does not match the current version (`current_etag`)
Built-in payload match templates (game servers and common protocols): used in a rule as match.payload.template; the pattern is compared with a mask starting offset bytes after the start of the payload. The patterns are a starting point: verify them against your server version and monitor in learning mode first
permission: protection:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Protection profiles (static + managed): with the prefixes using them and rule hit counters. The response ETag header is the current protection version.
permission: protection:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Create a managed profile (ID 128-255 is assigned by the server). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Fully replace a managed profile (409 for a static profile). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
integer
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Delete a managed profile (409 if prefixes use it). If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
integer
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Responses
200
Success
400
Invalid request
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Not found
409
Static record (cannot be changed), already exists or in use (`used_by`)
412
If-Match does not match the current version (`current_etag`)
Apply the selected version's content as a NEW version (history is not deleted); it is re-validated against the current configuration. If-Match (ETag "p<n>") is an optional precondition; the response ETag header is the current protection version.
permission: protection:writeaudited
Parameters
Name
In
Type
Description
nrequired
path
integer
dry_run
query
boolean
true: validate and preview (diff, impact, warnings); nothing is written, no audit record is produced
Responses
200
Success
400
Invalid request
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Not found
409
Static record (cannot be changed), already exists or in use (`used_by`)
412
If-Match does not match the current version (`current_etag`)
Approve the mitigation: the prefix is switched to ENFORCE IMMEDIATELY. The decision maker and time are written to the audit chain and the attack record
permission: mitigation:decideaudited
Parameters
Name
In
Type
Description
idrequired
path
string
attack (incident) ID
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
No pending approval (already decided, expired, or the attack has ended)
429
Rate limited
501
Approval mechanism is disabled
503
Audit record could not be written (operation not performed)
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/mitigations/{id}/deny"
Upstream mitigation
RTBH / FlowSpec announcements to upstream routers.
GET/v1/escalations
Upstream entries (RTBH and FlowSpec): target, match, duration, remaining time, whether it is announced to the routers, announcement error. Source: manual (API/CLI), customer (the customer's BGP community; in memory only, removed when the customer withdraws), policy (suggestion awaiting approval). A tenant sees only its own entries
permission: escalation:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
429
Rate limited
501
Upstream entries need BGP to be enabled on this appliance
Create an RTBH or FlowSpec entry (admin/operator). RTBH: a single IP (/32, /128) within the tenant's space (authorized BGP prefix or protected prefix); appliance infrastructure addresses (GRE endpoints, internal addresses, BGP next-hop/router) are rejected. FlowSpec: destination prefix ≥ /24 (/48), optional proto, source prefix, source/destination ports, packet length; action discard or rate-limit (bit/s); for a non-host destination at least one additional match is required. Every entry has a duration (default 1 h, max 24 h); submitting the same entry again renews its duration. If tenant is empty, the single tenant covering the prefix is used
Reject a pending suggestion (the entry is deleted)
permission: escalation:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
integer
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Entry not found
429
Rate limited
501
Upstream entries need BGP to be enabled on this appliance
503
Audit record could not be written (operation not performed)
Response example map of any
{
"key": null
}
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/escalations/{id}/deny"
GRE tunnels
GRE tunnels used to return clean traffic.
GET/v1/tunnel-status
Tunnel system summary: number of tunnels, present in the kernel, operationally up, with errors; if ip_forward is off, clean traffic does not enter the tunnels; clamp_error if the MSS clamping rules could not be applied
permission: tunnel:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Customer GRE tunnels and their live state in the kernel (whether the interface exists, admin/oper state, MTU, addresses, counters, last reconcile error) with a health summary (live.health: ICMP probe to the inner peer address + BGP session → ok | degraded | down | unknown | disabled, rtt, loss, counters). A tenant sees only its own tunnels
permission: tunnel:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Create a tunnel (admin/operator). Validation: IPv4 endpoints, unique (local, remote, key), recursive routing (an endpoint cannot be inside a protected prefix), inner address pair in the same subnet, inner subnets do not overlap. A wsg<id> GRE interface is created in the kernel, the inner address is assigned and MSS clamping is added. The ID is assigned automatically
Fully replace a tunnel (ID and tenant do not change). If GRE parameters (local/remote/key/ttl) change, the interface is recreated (brief interruption); MTU, state and inner address change in place
Every announcement received from customers and its decision: active (being announced to the router), pending (accepted, waiting for data plane/route), rejected (reason stable code: not-authorized, too-long, bogon, as-loop, first-as, origin-as, origin-set, recursive, rpki-invalid, rpki-notfound, irr-no-route, superseded, tenant-quota, no-next-hop ...). Warnings for accepted ones (warnings) and the RPKI/IRR result are shown
permission: bgp:readread-only users
Parameters
Name
In
Type
Description
status
query
string
tunnel
query
integer
prefix
query
string
Responses
200
Success
400
Invalid filter
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Re-fetch IRR data now (admin/operator): after a new route object/AS-SET member is added to the registry, without waiting for the automatic refresh (hours). The result triggers re-evaluation
permission: bgp:writeaudited
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
409
IRR is not configured
429
Rate limited
501
BGP is not enabled on this appliance
503
Audit record could not be written (operation not performed)
Response example map of any
{
"key": null
}
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/bgp/refresh"
GET/v1/bgp/sessions
BGP sessions: customer sessions (per tunnel, peer AS, state, received/accepted prefixes) and router sessions (staff only). A tenant sees only its own customer sessions. md5 and gtsm indicate the session is protected with TCP-MD5 / GTSM; the password itself never appears in any response
permission: bgp:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Reset the tunnel's customer BGP session (admin/operator). That customer's prefixes are withdrawn until the session is re-established
permission: bgp:writeaudited
Parameters
Name
In
Type
Description
tunnelrequired
path
integer
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Tunnel or session not found
409
Engine could not reset
429
Rate limited
501
BGP is not enabled on this appliance
503
Audit record could not be written (operation not performed)
Response example map of any
{
"key": null
}
curl -X POST -H "Authorization: Bearer $WS_TOKEN" \
"https://mssp.example.com:8443/v1/bgp/sessions/{tunnel}/reset"
GET/v1/bgp/status
BGP summary: session count/established, received and announced prefix counts. Staff also see engine errors, total counters (accepted/withdrawn/per reject reason), and RPKI (RTR) and IRR source status; a tenant sees only its own summary
permission: bgp:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Appliance BGP settings (AS, router id, next hop announced to the routers, upstream router sessions such as the MX, RTBH and RPKI/IRR). TCP-MD5 passwords are never returned (only password_set)
permission: system:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Create a scheduled report definition (kind: manual|daily|weekly|monthly; tz, hour, weekday, day). type: incident + kind: attack_end: a report for each attack is generated automatically ~6 min after it ends (if tenant is given, only that customer's attacks). A new definition does not trigger catch-up runs for past due times
permission: report:writeaudited
Parameters
Name
In
Type
Description
dry_run
query
boolean
true: validate only (nothing is written, no audit record is produced)
Generate a report now (monthly_summary | tenant_sla | incident). Period: month | day | from+to; otherwise the previous month. deliver sends the PDF as an attachment to email channels; a report.ready event is published
Replace a channel; if secret is empty the existing secret is kept, clear_secret deletes it. Secret fields (secret) are write-only; they never appear in any response or audit record.
permission: notify:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
string
dry_run
query
boolean
true: validate only (nothing is written, no audit record is produced)
Add a local entry (category own or x6..x15; feed categories cannot be imitated). TTL 60 s..30 days (default 24 hours). There is no automatic blocklisting: with spoofed-source attacks it risks blocking innocent IPs
URL feeds: operator-defined plain-text IP/CIDR lists (e.g. Spamhaus DROP) and their status (last attempt/success, last error, entry and skipped line counts, next download). Query values in the URL that look secret (key/token/secret…) are masked
permission: ti:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Add a URL feed. The list is downloaded with a conditional GET every interval_s seconds (300..604800, default 3600; ≤ 32 MiB, 60 s timeout) and synchronized with category: lines added at the source are added, removed ones are deleted. One IP/CIDR per line; #, ;, // comments are stripped; IPv4 < /8 and IPv6 < /16 are skipped. A failed download (HTTP error, HTML page, limit exceeded) keeps the previous data. At most 32 feeds; 250 000 entries in total across all feeds. The first download runs within 30 s via the scheduler, or with refresh
Update a URL feed (omitted fields are unchanged). Category and enabled changes are applied to the kernel immediately; a disabled feed's data is kept but not applied. When the URL changes the feed is re-downloaded immediately (the old data is kept until the new data arrives)
Download and apply a URL feed now. The response waits at most 12 s; if the download takes longer it completes in the background and a view with fetching: true is returned
permission: ti:writeaudited
Parameters
Name
In
Type
Description
idrequired
path
string
URL feed ID (uf-…)
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
404
Feed not found
409
This feed is already downloading / total entry limit
429
Rate limited
501
Threat intelligence is not configured
502
Download or parsing failed (previous data kept)
503
Audit record could not be written (operation not performed)
Threat intelligence status: feed name/version/age (stale: older than 72 hours), entry counts per category, local entry count, effective entry count written to the kernel, rejected packets and matched traffic per category
permission: ti:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
ASN organization names (from MaxMind ASN data; e.g. 13335 → Cloudflare, Inc.). asn: up to 200 comma-separated ASNs (AS prefix optional). Unknown ones are omitted from the response; empty if there is no database
permission: prefix:readread-only users
Parameters
Name
In
Type
Description
asn
query
string
Responses
200
Success
400
Invalid ASN / too many ASNs
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
GeoIP/ASN database status: record counts (v4/v6), distinct country/ASN counts, source name, content SHA-256, import time/user and data plane counters (lookups, sources not in the database, policy matches)
permission: geo:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
MaxMind GeoLite automatic update status: whether configured, account ID, whether a key is set (the key itself is NEVER returned), interval, last attempt/success/error, next run time, applied version
permission: geo:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Totals of traffic matching no rule by {proto, family, port/ICMP type}, most packets first. Used to write rules during dry-run; suggested_rule is a sample rule that would allow this traffic (none for ICMP: errors/ND are built in)
permission: selfprot:readread-only users
Parameters
Name
In
Type
Description
limit
query
integer
maximum entries (1-1000), default 100
Responses
200
Success
400
Invalid limit
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
License status: state (none|not_yet|valid|grace|expired), customer/edition/features/limits, days remaining, grace period end, appliance ID (machine_id; give it to the vendor to bind the license to this appliance). 501 if license management is disabled. PROTECTION NEVER stops because of the license: the license only limits adding NEW features/resources
permission: license:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Certificate served to the web panel (management and local customer portal listeners): source ("" internal/self-signed | upload | acme), names, issuer, expiry, fingerprint; Let's Encrypt settings (the Cloudflare token only as token_set), last attempt and error, available validation methods. The internal certificate pinned by the portal server is NOT changed by this endpoint
permission: system:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Connection of the separate portal server: listener ports, allowed portal server addresses and client certificate fingerprints, and this appliance's certificate fingerprint for pinning
permission: system:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change
Routed (L3) inline mode: data port addresses (MX204 / QFX side), QFX next-hop, return path and live state (links, next-hop ARP, installed prefix routes)
permission: system:readread-only users
Responses
200
Success
401
Authentication required
403
Forbidden: missing permission, another customer's resource, or a read-only token used for a change