Get a header rule

GET

/domains/{domain}/rules/header/{ruleId}

const url = 'https://api.nsin.ir/domains/example.com/rules/header/1';
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/1 \
  --header 'Authorization: Bearer <token>'

Requires domain.view.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

ruleId

required

integer

Numeric id of the rule.

Responses

200

The rule.

application/json

object

integer

domain_id

integer

record_id

Deprecated single-record scope. Prefer record_ids. Absent for zone-wide rules.

integer

record_ids

The proxied DNS records this rule applies to. Empty or absent means zone-wide — every proxied record of the domain.

Array<integer>

type

string

Allowed values: cache drop redirect rewrite waf captcha rate_limit bot_route origin_pool origin_route fingerprint error_page optimize basic_auth header

enabled

boolean

priority

Evaluation order; lower runs first. Defaults to 100.

integer

host_pattern

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.

string

host_match_type

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.

string

Allowed values: "" exact wildcard regex

host_includes

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.

Array<string>

host_excludes

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.

Array<string>

ip_includes

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.

Array<string>

<= 256 items

ip_excludes

Client addresses carved back out of ip_includes. An exclude always wins over an include. Canonicalised on the way in, exactly like ip_includes.

Array<string>

<= 256 items

action_mode

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.

string

Allowed values: enforce dry_run

created_at

string format: date-time

updated_at

string format: date-time

path_match_type

How path_includes and path_excludes are interpreted.

string

Allowed values: wildcard regex

path_includes

Paths the rule applies to. Defaults to ["/*"] — everything.

Array<string>

path_excludes

Paths carved back out of path_includes.

Array<string>

name

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.

string

<= 64 characters

ops

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.

Array<object>

>= 1 items <= 16 items

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

direction

required

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.

string

Allowed values: request response

action

required

set — replace every existing value with value.
add — append value, keeping what the client or origin sent.
remove — delete the header. The only action that accepts a trailing * wildcard in name.

string

Allowed values: set add remove

name

required

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.

string

<= 256 characters

value

Required for set and add, and must be empty for remove.

string

<= 4096 characters

Example

{
  "type": "cache",
  "host_match_type": "",
  "action_mode": "enforce",
  "path_match_type": "wildcard",
  "ops": [
    {
      "direction": "request",
      "action": "set"
    }
  ]
}

401

Missing, malformed, revoked or expired API key — or the owning account is inactive.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

404

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.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}