Skip to content
nsin docs
EN فا

Create a custom rule

POST
/domains/{domain}/rules/custom/
 
curl --request POST \
  --url https://api.nsin.ir/domains/example.com/rules/custom/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Padding cookie flood", "action": "block", "action_mode": "dry_run", "conditions": [ { "field": "cookie", "key": "padding", "op": "exists" } ] }'

Creates an expression firewall rule. Requires rules.edit.

How many custom rules a domain may hold is the plan’s max_custom_rules (see GET /domains/{domain}/features); at the limit the create answers 403. If the domain’s plan does not include this rule type, the rule is still created — but switched off (enabled: false), whatever the body says.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
domain
required
string

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

Example 
example.com

Request Body required

Section titled “Request Body required ”
Media type application/json
object
record_id

Deprecated single-record scope. Prefer record_ids.

integer | null
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

Label the rule is listed under.

string
<= 80 characters
match

all: every condition must be true (AND); any: one is enough (OR).

string
default: all
Allowed values: all any
conditions

1–20 conditions; at most 16 KB together as JSON.

Array<object>
>= 1 items <= 20 items

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
field
required

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.

string
Allowed values: cookie header query path method host user_agent referer ip country asn ja4 ja4h bot_score
key

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.

string
<= 128 characters
op
required

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.

string
Allowed values: exists equals contains starts_with ends_with matches in lt gt
values

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).

Array<string>
<= 100 items
negate

Flip the result — “is not”, “does not contain”, “does not exist”.

boolean
ignore_case

Compare text case-insensitively. Not allowed on ip, country or asn; method and host always compare case-insensitively.

boolean
action

block answers with the 403 block page (as a drop rule does); captcha challenges the visitor and lets them through once solved; log lets the request through and only records it. Request logs tag a match as detectAction custom_block, custom_captcha or custom_log; a dry_run match carries the dry-run flag.

string
default: block
Allowed values: block captcha log
Example 
{
  "name": "Padding cookie flood",
  "action": "block",
  "action_mode": "dry_run",
  "conditions": [
    {
      "field": "cookie",
      "key": "padding",
      "op": "exists"
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Rule created.

Media type application/json
object
id
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

Label the rule is listed under.

string
<= 80 characters
match

all: every condition must be true (AND); any: one is enough (OR).

string
default: all
Allowed values: all any
conditions

1–20 conditions; at most 16 KB together as JSON.

Array<object>
>= 1 items <= 20 items

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
field
required

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.

string
Allowed values: cookie header query path method host user_agent referer ip country asn ja4 ja4h bot_score
key

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.

string
<= 128 characters
op
required

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.

string
Allowed values: exists equals contains starts_with ends_with matches in lt gt
values

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).

Array<string>
<= 100 items
negate

Flip the result — “is not”, “does not contain”, “does not exist”.

boolean
ignore_case

Compare text case-insensitively. Not allowed on ip, country or asn; method and host always compare case-insensitively.

boolean
action

block answers with the 403 block page (as a drop rule does); captcha challenges the visitor and lets them through once solved; log lets the request through and only records it. Request logs tag a match as detectAction custom_block, custom_captcha or custom_log; a dry_run match carries the dry-run flag.

string
default: block
Allowed values: block captcha log
expression

The conditions as text, for display only — ignored on write. Per condition [not ]<field>[["key"]] <op> <value | {v1 v2}> with equals printed as eq, keys and values as JSON string literals, one value bare and several (and every in list) in braces, (ignore case) appended when set; joined by and (match all) or or (match any). Example: cookie["padding"] exists and not user_agent contains "Chrome".

string
Example 
{
  "type": "cache",
  "host_match_type": "",
  "action_mode": "enforce",
  "path_match_type": "wildcard",
  "match": "all",
  "conditions": [
    {
      "field": "cookie",
      "op": "exists",
      "negate": false,
      "ignore_case": false
    }
  ],
  "action": "block"
}

400

Section titled “400 ”

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.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example foreignRecords 
{
  "error": "record_ids do not belong to this domain"
}

401

Section titled “401 ”

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example invalidKey 
{
  "error": "invalid API key"
}

402

Section titled “402 ”

The domain has no active plan at all, so no plan feature is available on it. Buy or renew a plan for the domain. (A plan that is active but does not include the feature answers 403 instead.)

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example noPlan 
{
  "error": "This domain does not have an active plan."
}

403

Section titled “403 ”

The key is read-only, the domain is at its plan’s max_rules_per_set, or it already holds max_custom_rules custom rules.

Media type 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

Section titled “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.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example notFound 
{
  "error": "not found"
}

429

Section titled “429 ”

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

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example limited 
{
  "error": "rate limit exceeded"
}