List custom rules

GET

/domains/{domain}/rules/custom/

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

Expression firewall rules: conditions on any cookie, header, query parameter, path, method, host, user agent, referer, client IP, country or JA4/JA4H fingerprint, combined with all (AND) or any (OR), then block, captcha or log. The edge runs them right after drop rules.

Returned in evaluation order. 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

Responses

200

Custom rules.

application/json

Array

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

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

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

401

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

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

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