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

• Production

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

• bearerAuth
• apiKeyAuth

Parameters

Path Parameters

domain

required

string

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

Example

example.com

Responses

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

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>

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. geo routes by edge node — see node_ids on each origin.

string

Allowed values: round_robin least_load geo

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.

integer

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.

string

host_header

Host header (and SNI) sent to the pool’s origins.

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"
      }
    ],
    "health_check": {
      "path": "/",
      "interval_sec": 15,
      "timeout_sec": 5,
      "unhealthy_threshold": 3,
      "healthy_threshold": 2,
      "eject_sec": 30
    }
  }
]

401

Missing, malformed, revoked or expired API key — or the owning account is inactive.

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

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

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