List header rules
const url = 'https://api.nsin.ir/domains/example.com/rules/header/';const options = {method: 'GET', 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 GET \ --url https://api.nsin.ir/domains/example.com/rules/header/ \ --header 'Authorization: Bearer <token>'Adds, overrides and removes HTTP headers — on the request before it reaches the origin, on the response before it reaches the visitor, or both from the same rule.
Returned in evaluation order. Requires domain.view.
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.comResponses
Section titled “ Responses ”Header rules.
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.
Optional label for this rule, e.g. “Security headers”, shown in the panel’s rule table. Purely for identification. Omit or send an empty string for none.
The ordered edit list, applied in array order.
Caps, all validated on save so an oversized rule fails as a
clear 400 instead of as a 431 from the origin: 16 ops per rule,
4096 bytes per value, and 8192 bytes summed over name+value of
every set/add op — 4 KB leaves room for a real
Content-Security-Policy while staying under the 8 KB per-header
limit nginx and Apache default to.
Headers NSIN owns are refused, per (direction, action, name)
rather than by name alone. On the request: Host, the framing and
hop-by-hop set (Content-Length, Transfer-Encoding,
Connection, Upgrade, Keep-Alive, Proxy-Connection, TE,
Trailer), the forwarding set (X-Forwarded-*, X-Real-IP,
Forwarded, True-Client-IP, CDN-Loop), the conditional and
negotiation set (Cache-Control, If-None-Match,
If-Modified-Since, If-Match, If-Range, Range,
Accept-Encoding), Sec-WebSocket-*, X-Mafar-*, X-Nsin-* and
the whole Nsn-* prefix. On the
response: Content-Length, the hop-by-hop set,
Content-Encoding, Vary, Server, Strict-Transport-Security
(managed by the HSTS ramp on the domain’s Security page) and again
Nsn-*.
Three request headers are blocked for set/add but allowed for
remove: Cookie, Authorization and Nsn-Connecting-IP.
Re-adding a credential is what makes a personalised page cacheable
in a shared slot; stripping one before it reaches the origin is a
legitimate privacy choice, and is how an owner makes a page
cacheable that otherwise would not be.
Each refusal returns a 400 naming the header, the action and the
reason.
Two response names are accepted but dangerous, and the panel
makes a human type the header name to confirm before saving one:
Cache-Control, which desyncs the browser’s view of freshness from
the edge’s, and Set-Cookie, which on a cacheable page is the shape
of a cross-account session leak. The API applies no confirmation
step — an integration writing either one should know why.
One header edit. A rule carries an ordered list of them and applies them in slice order, so a later op beats an earlier one on the same name.
object
request— applied on the way to the origin, after NSIN has stamped its own forwarding headers.response— applied on the way to the visitor, after the response is retrieved from cache or origin. Nothing a response op does reaches the stored copy, so editing a rule takes effect on the very next cache hit rather than when the object expires.
A 101 WebSocket handshake never passes the response chokepoint, so response ops do not apply to an upgrade.
set— replace every existing value withvalue.add— appendvalue, keeping what the client or origin sent.remove— delete the header. The only action that accepts a trailing*wildcard inname.
The header field name — an RFC 9110 token, matched
case-insensitively. A trailing * (X-Debug-*) is a prefix
wildcard and is accepted on remove only; the edge re-checks the
blocked list against every name a wildcard actually matches, so a
wildcard can never strip a header NSIN owns.
Some names are refused per (direction, action) rather than
outright — see ops on the request body for the list and the
reasoning.
Required for set and add, and must be empty for remove.
Example
[ { "type": "cache", "host_match_type": "", "action_mode": "enforce", "path_match_type": "wildcard", "ops": [ { "direction": "request", "action": "set" } ] }]Missing, malformed, revoked or expired API key — or the owning account is inactive.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "invalid API key"}No such domain, or your role on it does not permit this operation. The
rules endpoints deliberately answer 404 rather than 403 for an
insufficient role, so they never confirm that a domain exists to someone
who cannot use it.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "not found"}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"}