Enable or disable an origin pool rule

PATCH

/domains/{domain}/rules/origin_pool/{ruleId}/toggle

const url = 'https://api.nsin.ir/domains/example.com/rules/origin_pool/1/toggle';
const options = {method: 'PATCH', 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 PATCH \
  --url https://api.nsin.ir/domains/example.com/rules/origin_pool/1/toggle \
  --header 'Authorization: Bearer <token>'

Flips the rule’s enabled flag. Takes no request body — the new state is always the opposite of the current one, and is returned. Requires rules.edit.

Switching a rule on is refused with 402 when the domain’s plan does not include its type; switching it off always works.

Authorizations

bearerAuth
apiKeyAuth

Parameters

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

200

The rule in its new state.

application/json

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

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

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

402

The request would switch on a rule whose type the domain’s plan does not include, or the domain has no active plan at all. Such a rule can be created, edited and switched off, but it stays off until the plan includes its type: buy or upgrade the domain’s plan, then switch it on.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

{
  "error": "This rule type is not on this domain's plan. The rule is saved switched off — buy or upgrade this domain's plan to switch it on."
}

{
  "error": "This domain has no active plan. Buy a plan for this domain to switch rules on."
}

403

The key is read-only and this endpoint is a write. Read-only keys may only issue GET, HEAD and OPTIONS.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

readOnly

{
  "error": "read-only API key"
}

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.

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

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