Update a redirect rule
const url = 'https://api.nsin.ir/domains/example.com/rules/redirect/1';const options = { method: 'PUT', 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"],"target":"example","status_code":301,"preserve_query":true,"preserve_path":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://api.nsin.ir/domains/example.com/rules/redirect/1 \ --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" ], "target": "example", "status_code": 301, "preserve_query": true, "preserve_path": true }'Partial update — omitted fields keep their current value. Requires
rules.edit.
Setting enabled: true on a rule whose type the domain’s plan does not
include is refused with 402; every other change is allowed.
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.
Request Body required
Section titled “Request Body required ”object
Deprecated single-record scope. Prefer 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.
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 omitted means every host. Sending an explicit empty array clears an existing list.
Hostnames excluded from the rule; excludes beat 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_excludesand leaveip_includesempty. - 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.
Client addresses excluded from the rule; excludes beat includes.
Same three entry forms, same canonicalisation and same cache /
optimize refusal as 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.
Where to send the visitor. Absolute URL, or a path when redirecting within the site.
The redirect status. 301/308 are permanent and cached hard by
browsers — verify the rule with 302 first.
Append the original query string to target.
Append the original path to target.
Responses
Section titled “ Responses ”The updated rule.
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.
Where to send the visitor. Absolute URL, or a path when redirecting within the site.
The redirect status. 301/308 are permanent and cached hard by
browsers — verify the rule with 302 first.
Append the original query string to target.
Append the original path to target.
Only present when creating the canonical www.<domain> →
apex (or apex → www.<domain>) redirect. Those rules are inert
without a proxied DNS record for www — the edge evaluates
rules only for hostnames it holds a record for — so the record
is provisioned alongside the rule and this reports what
happened: created (a proxied www record mirroring the apex
was added), created_external (added, but the zone is hosted
elsewhere so the owner must still point www at us),
covered (one already existed), unproxied (a www
record exists but bypasses the edge, so the redirect will not
run), no_apex (no apex address record to mirror), limit
(the plan is out of record slots), failed (the DNS write
failed). The rule itself is created in every case.
Example
{ "type": "cache", "host_match_type": "", "action_mode": "enforce", "path_match_type": "wildcard", "status_code": 301, "preserve_query": true, "www_record": "covered"}Malformed body, an invalid field value, or record_ids containing a
record that does not belong to this domain. Cache and header rules
also refuse record_ids naming a gateway record.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "record_ids do not belong to this domain"}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"}