List Firewall Policies
List the WAF/firewall policies on the calling user's account. Firewall policies are evaluated before traffic policies — a request blocked by the firewall never reaches the agent. Each policy has an action (allow or block) and a list of conditions; if all conditions match, the action fires.
Policies are evaluated in priority order (lower first). The first matching policy determines the verdict; subsequent policies are skipped (allow-list / block-list semantics).
Distinct from traffic policies: firewall policies are account-wide and binary (allow/block), while traffic policies attach per-endpoint and can do rich actions (rate limit, redirect, transform).
Query parameters
enabled boolean
Filter to enabled (
true) or disabled (false) policies. Omit for all.include_conditions boolean
Default
true — each policy carries its full conditions array. Set false to omit conditions for a lighter response.page, page_size int
Opt-in pagination. Omitting
page returns the full set. When page is supplied without page_size, the page size is 15; values above 200 are capped at 200. When paginated, the response object also carries total, page, and page_size.Response (200 OK)
policies object[]
The policies, ordered by
priority ascending (fields below). Always present; [] when there are none.posture object?
Firewall activity in your account over the last 24 hours:
blocked (int, requests a firewall policy blocked), top_source (string, the client IP blocked most often; empty when none) and top_source_n (int, how often it was blocked). Omitted when the summary can't be computed.page, page_size, total int?
Only when you sent
page: the page returned, the effective page size, and the number of matching policies across all pages.Policy object
id string (uuid)
Policy uuid. Used in /policies/{uuid}.
uuid string (uuid)
The same value as
id (every object in the API carries uuid).user_uuid string (uuid)?
The user who created the policy.
account_uuid string (uuid)?
Owning account (omitted when null).
name string
Free-form label.
description string?
Free-form description. Omitted when unset.
action string
allow, block or challenge. allow stops further policy evaluation and lets the request through; block rejects (HTTP 403 by default, or the account's custom firewall error template if active); challenge makes HTTP visitors pass the edge browser check first and blocks on TCP/UDP endpoints.priority int
Lower runs earlier. Default
100.enabled boolean
false skips this policy at evaluation time.conditions array?
The policy's conditions. Omitted when
include_conditions=false and when the policy has no conditions — a policy with zero conditions matches every request (use carefully). Each condition: {id, uuid, policy_id, policy_uuid, condition_type, operator, condition_value, logical_operator, created_at} (id = uuid, policy_id = policy_uuid, all uuid strings).hit_count int
Requests this policy matched over the last 7 days (best-effort;
0 when none or when the stats can't be read).last_matched, hits_daily datetime? / int[]?
The most recent match in that window and a per-day match series (index 0 = oldest day). Both omitted when the policy hasn't matched in the window.
shadowed, shadow_reason boolean? / string?
Present only when a higher-priority catch-all renders this policy unreachable (
shadowed: true plus a human-readable reason). Only computed when conditions are loaded.quota_paused_at datetime?
Set while the policy is paused because the account has more firewall policies than its plan allows: it is kept but not enforced, and resumes on its own once the account has room. Omitted otherwise.
created_at, updated_at datetime
RFC 3339 UTC.
Deprecated: until the sunset this response also carries the legacy integer user_id and account_id fields. Don't use them; read user_uuid and account_uuid.
Errors
401 Unauthorized
Missing auth.
Request
curl "https://api.ngris.com/v1/firewall/policies" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
for p in client.firewall.list_policies():
print(f"[{p['priority']:>3}] {p['action']:<6} {p['name']}")
Response — 200 OK
{
"policies": [
{
"id": "019c32cb-35d7-786f-b2c5-d108951e23d8",
"uuid": "019c32cb-35d7-786f-b2c5-d108951e23d8",
"user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
"name": "block-tor",
"description": "Block known Tor exit nodes",
"action": "block",
"priority": 10,
"enabled": true,
"conditions": [
{"id": "019c4790-e565-733a-8f1b-52bc76befe65", "uuid": "019c4790-e565-733a-8f1b-52bc76befe65",
"policy_id": "019c32cb-35d7-786f-b2c5-d108951e23d8", "policy_uuid": "019c32cb-35d7-786f-b2c5-d108951e23d8", "condition_type": "country",
"operator": "in", "condition_value": "RU, KP", "logical_operator": "AND",
"created_at": "2026-04-01T00:00:00Z"}
],
"hit_count": 42,
"last_matched": "2026-04-29T12:58:10Z",
"hits_daily": [3, 5, 8, 4, 6, 9, 7],
"created_at": "2026-04-01T00:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}
],
"posture": {
"blocked": 9,
"top_source": "203.0.113.77",
"top_source_n": 4
}
}
Was this helpful?