Skip to content
nsin docs
EN فا

Get a captcha rule

GET
/domains/{domain}/rules/captcha/{ruleId}
 
curl --request GET \
  --url https://api.nsin.ir/domains/example.com/rules/captcha/1 \
  --header 'Authorization: Bearer <token>'

Returns one captcha rule by id. A rule that does not exist, belongs to another domain or to another rule type answers 404, as does a domain you cannot read. Requires domain.view.

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
ruleId
required
integer

Numeric id of the rule.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The rule.

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>
ttl_sec

How long a solved challenge is remembered for that visitor, in seconds.

integer
managed_by

under_attack on Under Attack Mode’s rule, which the rule endpoints refuse to change (403); empty on your own rules.

string
Allowed values: "" under_attack
Example 
{
  "type": "cache",
  "host_match_type": "",
  "action_mode": "enforce",
  "path_match_type": "wildcard",
  "managed_by": ""
}

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

404

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

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

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