Enable or disable a rate limit rule
const url = 'https://api.nsin.ir/domains/example.com/rules/rate-limit/1/toggle';const options = {method: 'PATCH', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.nsin.ir/domains/example.com/rules/rate-limit/1/toggle \ --header 'Authorization: Bearer <token>'Flips the rule’s enabled flag. Takes no request body — the new state
is always the opposite of the current one, and is returned. Requires
rules.edit.
Switching a rule on is refused with 402 when the domain’s plan does
not include its type; switching it off always works.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The domain name (for example example.com) — not a numeric id.
Example
example.comNumeric id of the rule.
Responses
Section titled “ Responses ”The rule in its new state.
object
Deprecated single-record scope. Prefer record_ids. Absent for
zone-wide rules.
The proxied DNS records this rule applies to. Empty or absent means zone-wide — every proxied record of the domain.
Evaluation order; lower runs first. Defaults to 100.
Legacy single-hostname filter, kept for rules written before
host_includes existed. It is evaluated as one more entry of
host_includes; prefer the lists.
How the host filter — host_pattern, host_includes and
host_excludes — is matched. One strategy covers all three, exactly as
one path_match_type covers both path lists.
The empty string means “no host filter”, and is the only valid value
when the pattern and both lists are empty. Set a list without a match
type and the API defaults it to wildcard.
A wildcard entry matches subdomains, not the label itself:
*.example.com covers shop.example.com but not example.com — the
same reading as the DNS wildcard. Add the bare name as its own entry to
include it.
Hostnames the rule applies to. Empty or absent means every host the
scoped record(s) serve — which on a wildcard-proxied zone
(*.example.com) is every subdomain.
Hostnames carved back out of host_includes. An exclude always
wins over an include, so “everything except staging” is an empty
include list plus one exclude.
Client addresses the rule applies to. Empty or absent means every
address — the rule is not scoped by IP at all unless ip_excludes
is set.
Entries are returned canonicalised, which may differ from what was
sent: CIDR host bits are masked off (10.0.0.5/8 reads back as
10.0.0.0/8), range endpoints are ordered low-to-high, IPv4-mapped
IPv6 is unmapped, and duplicates are dropped. The order of the
remaining entries is preserved.
The address matched is the TCP peer seen by the edge. X-Forwarded-For
is never consulted, so a visitor cannot spoof a header to put
themselves inside or outside a scope.
Client addresses carved back out of ip_includes. An exclude always
wins over an include. Canonicalised on the way in, exactly like
ip_includes.
enforce— the rule acts (block, redirect, challenge, …).dry_run— the rule matches and is logged as “would have acted”, but the request reaches the origin unchanged. Use it to test a rule safely.
Not every rule type honours this; cache ignores it.
How path_includes and path_excludes are interpreted.
Paths the rule applies to. Defaults to ["/*"] — everything.
Paths carved back out of path_includes.
Requests allowed per window_sec for one key.
Length of the counting window, in seconds.
How requests are bucketed. ip counts everything from one address
together; ip_path counts each path separately per address.
What happens to requests above the limit.
Extra requests tolerated momentarily above limit.
Only count requests with these HTTP methods. Empty or omitted counts every method. A request with another method skips this rule and is checked against the next rate limit rule in priority order.
What one counter is keyed by: up to 4 parts combined into one key.
When set it replaces key_by (which is still returned, as ip, or
ip_path for exactly [ip, path], for edges that predate this
field). A part a request lacks counts as empty, so every request
without that cookie or header shares one counter — often exactly
what you want against bots. Counting is per edge location.
object
ip_prefix is the client’s /24 (IPv4) or /64 (IPv6); asn the
client IP’s AS number; header, cookie and query the value of
the one named in key.
The header, cookie or query parameter name. Required for those three parts, absent for every other.
How match_conditions combine.
Only count requests that match these conditions (the custom rule condition objects). Empty means every request in scope counts.
One test on the request. TRUE when ANY of values matches; negate
flips the result. A missing cookie, header, query parameter or referer
makes every op except exists false — so a negated contains on a
missing cookie is true.
object
What to test. bot_score is the edge’s bot score of the request,
1 (bot) to 99 (human-like); a request the edge did not score never
matches. path is the request path before any rewrite,
host is lowercased without the port, ip is the TCP peer (never
X-Forwarded-For), country the visitor’s GeoIP country (XX
when unknown), asn the client IP’s autonomous system number (an
address with no known ASN never matches), ja4/ja4h NSIN’s own
fingerprints as shown in the request logs.
The cookie or header name — required for cookie and header.
For query, a parameter name, or empty for the whole raw query
string. Must be empty for every other field.
bot_score takes only lt or gt with exactly one value, a whole
number 1–99 (expression bot_score lt "30"); it is accepted once the
edge update that computes bot scores is live everywhere (until then
400). ip, country and asn take only in. Every other field takes
exists, equals, contains, starts_with, ends_with or
matches (an RE2 regex of up to 256 characters). exists is only
for cookie, header, referer and query with a key.
1–100 values, empty for exists. ip: single addresses or CIDRs
(v4 or v6), stored canonicalized. country: ISO 3166-1 alpha-2
codes, stored uppercase. asn: AS numbers 1–4294967295 (an AS
prefix is accepted), stored as plain decimals. An empty value is refused for contains,
starts_with, ends_with and matches (it would match every
request).
Flip the result — “is not”, “does not contain”, “does not exist”.
Compare text case-insensitively. Not allowed on ip, country or asn; method and host always compare case-insensitively.
After a key breaches the limit, keep answering on_breach for that
key this many seconds. 0 = only while it is over the limit.
Example
{ "type": "cache", "host_match_type": "", "action_mode": "enforce", "path_match_type": "wildcard", "window_sec": 60, "key_by": "ip", "on_breach": "drop", "methods": [ "GET" ], "key_parts": [ { "part": "ip" } ], "match": "all", "match_conditions": [ { "field": "cookie", "op": "exists", "negate": false, "ignore_case": false } ], "block_for_sec": 0}Missing, malformed, revoked or expired API key. (A valid key whose
account has been deactivated gets 403 account is inactive instead.)
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "invalid API key"}The request would switch on a rule whose type the domain’s plan does not include, or the domain has no active plan at all. Such a rule can be created, edited and switched off, but it stays off until the plan includes its type: buy or upgrade the domain’s plan, then switch it on.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "This rule type is not on this domain's plan. The rule is saved switched off — buy or upgrade this domain's plan to switch it on."}{ "error": "This domain has no active plan. Buy a plan for this domain to switch rules on."}The key is read-only and this endpoint is a write. Read-only keys may
only issue GET, HEAD and OPTIONS.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "read-only API key"}The domain or the rule does not exist, the rule belongs to another domain or another rule type, or your role does not permit this operation.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Example
{ "error": "read-only API key"}The key exceeded its request budget (300 requests per minute by default).
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "rate limit exceeded"}