Skip to content
nsin docs
EN فا

List origin pool rules

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

Load-balances matching traffic across several origins with optional health checking. Overrides the DNS record’s own destination for every path it matches.

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

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Origin pool rules.

Media type application/json
Array
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
lb_type

How traffic is spread across origins.

  • round_robin — weighted rotation across every origin.
  • least_load — the origin with the fewest in-flight requests.
  • geo — routes by edge node; see node_ids on each origin.
  • ha — active/passive failover. All traffic goes to the lowest priority tier that still has a healthy origin, and cascades to the next tier only once a whole tier is down.

ha has two extra requirements, each a 400 when unmet:

  • at least two distinct origins[].priority values — a single tier has nothing to fail over to;
  • health_check.enabled must be true. Standby origins take no real traffic, so without active probes the edge can never observe the primary going down, nor the standby recovering, and would pin every request to tier 1 forever.
string
default: round_robin
Allowed values: round_robin least_load geo ha
origins
Array<object>

One origin in a pool.

object
address
required

Origin IP address or hostname.

string
port
integer
scheme
string
Allowed values: http https
weight

Relative share of traffic under round_robin and least_load. Under ha it still applies, weighting round-robin within a priority tier. Defaults to 1.

integer
priority

Failover tier under lb_type: ha. Lower is preferred — 1 is the primary tier, 2 the first standby, and so on, the same direction as the rule’s own priority. Origins sharing a number form one tier and load-balance across it.

Only ha reads this field; the other strategies ignore it and leave it untouched, so switching lb_type back and forth loses nothing. Omitted or 0 is normalised to 1.

integer
default: 1 >= 1 <= 100
node_ids

Under lb_type: geo, the edge nodes that use this origin.

Array<integer>
country

ISO country code of this origin.

string
health_check
object
enabled
boolean
path

Probe path.

string
default: /
interval_sec

Seconds between active probes.

integer
default: 15
timeout_sec

Probe timeout in seconds.

integer
default: 5
unhealthy_threshold

Consecutive probe failures before an origin is marked down.

integer
default: 3
healthy_threshold

Consecutive probe successes before an origin returns to service.

integer
default: 2
eject_sec

How long a passively ejected origin stays out, in seconds.

integer
default: 30
host

Host header override for the probe. Must be inside this domain or another active domain of the same owner.

string
host_header

Host header (and SNI) sent to the pool’s origins. Must be inside this domain or another active domain of the same owner.

string
name

Optional label for this pool, shown in the panel’s rule table and next to the records it overrides. Purely for identification — it does not affect routing. Omit or send an empty string for none.

string
<= 64 characters
Example 
[
  {
    "type": "cache",
    "host_match_type": "",
    "action_mode": "enforce",
    "lb_type": "round_robin",
    "origins": [
      {
        "scheme": "http",
        "priority": 1
      }
    ],
    "health_check": {
      "path": "/",
      "interval_sec": 15,
      "timeout_sec": 5,
      "unhealthy_threshold": 3,
      "healthy_threshold": 2,
      "eject_sec": 30
    }
  }
]

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 ”

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