Create a header rule

POST

/domains/{domain}/rules/header/

const url = 'https://api.nsin.ir/domains/example.com/rules/header/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"record_id":1,"record_ids":[1],"enabled":true,"priority":100,"host_pattern":"example","host_match_type":"","host_includes":["example"],"host_excludes":["example"],"ip_includes":["example"],"ip_excludes":["example"],"action_mode":"enforce","path_match_type":"wildcard","path_includes":["example"],"path_excludes":["example"],"name":"example","ops":[{"direction":"request","action":"set","name":"example","value":"example"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.nsin.ir/domains/example.com/rules/header/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "record_id": 1, "record_ids": [ 1 ], "enabled": true, "priority": 100, "host_pattern": "example", "host_match_type": "", "host_includes": [ "example" ], "host_excludes": [ "example" ], "ip_includes": [ "example" ], "ip_excludes": [ "example" ], "action_mode": "enforce", "path_match_type": "wildcard", "path_includes": [ "example" ], "path_excludes": [ "example" ], "name": "example", "ops": [ { "direction": "request", "action": "set", "name": "example", "value": "example" } ] }'

Adds, overrides and removes HTTP headers on the request, the response, or both. Unlike every other rule type, header rules compose: every matching rule runs, in priority order.

Not available on the Free plan, and refused on gateway records. Requires rules.edit.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

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

Example

example.com

Request Body^required

application/json

object

record_id

Deprecated single-record scope. Prefer record_ids.

integer

nullable

record_ids

Scope the rule to these proxied records. Omit or send an empty array for a zone-wide rule. Every id must belong to this domain.

Array<integer>

enabled

boolean

default: true

priority

integer

default: 100

host_pattern

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 omitted means every host. Sending an explicit empty array clears an existing list.

Array<string>

<= 200 items

host_excludes

Hostnames excluded from the rule; excludes beat includes.

Array<string>

<= 200 items

ip_includes

Scope the rule to these client addresses. Empty or omitted means every address; sending an explicit empty array clears an existing list.

Together with ip_excludes these two lists express all four client-IP semantics, so there is no separate match-type field:

IP is in a list — put the addresses in ip_includes.
IP is not in a list — put them in ip_excludes and leave ip_includes empty.
IP equals X — a one-entry ip_includes.
IP does not equal X — a one-entry ip_excludes.

Each entry is one of three forms:

a bare address, IPv4 or IPv6 — 203.0.113.7, 2001:db8::1
a CIDR prefix — 203.0.113.0/24, 2001:db8::/32
an inclusive low-high range — 203.0.113.10-203.0.113.40. Both endpoints must be the same IP version.

Entries are canonicalised and de-duplicated on save (CIDR host bits masked off, range endpoints ordered, IPv4-mapped IPv6 unmapped), so the stored value is exactly what the edge will match. An entry that is not a valid address, CIDR or range is a 400.

An empty ip_includes means every address, subject to ip_excludes; an exclude always beats an include. Matching is against the TCP peer at the edge, never X-Forwarded-For, so the scope cannot be spoofed with a request header.

Not accepted on cache and optimize rules — a non-empty list on either type is a 400. One cached copy is shared by every visitor and the cache key carries no client-IP dimension, so an IP-scoped cache rule would serve one visitor’s response to another.

On a drop rule, ip_excludes may not be used on its own: exclude-only would blackhole every visitor who is not named, so ip_includes must list at least one address.

Array<string>

<= 256 items

ip_excludes

Client addresses excluded from the rule; excludes beat includes. Same three entry forms, same canonicalisation and same cache / optimize refusal as 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

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

Responses

200

Rule created.

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.

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.

Each refusal returns a 400 naming the header, the action and the reason.

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

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"
    }
  ]
}

400

Malformed body, an invalid field value, or record_ids containing a record that does not belong to this domain.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

foreignRecords

{
  "error": "record_ids do not belong to this domain"
}

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"
}

403

The key is read-only, or the domain’s plan does not include this rule type or allows fewer rules of it than you already have.

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"
}

404

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.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

notFound

{
  "error": "not found"
}

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"
}

Create a header rule

Authorizations

Parameters

Path Parameters

Example

Request Body required

Responses

200

Example

400

Examples

401

Examples

403

Example

404

Examples

429

Examples

Request Body^required