Skip to content
nsin nsin nsin Docs

Create a origin pool rule

POST
/domains/{domain}/rules/origin_pool/
 
curl --request POST \
  --url https://api.nsin.ir/domains/example.com/rules/origin_pool/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "record_id": 1, "record_ids": [ 1 ], "enabled": true, "priority": 100, "host_pattern": "example", "host_match_type": "", "action_mode": "enforce", "lb_type": "round_robin", "origins": [ { "address": "example", "port": 1, "scheme": "http", "weight": 1, "node_ids": [ 1 ], "country": "example" } ], "health_check": { "enabled": true, "path": "/", "interval_sec": 15, "timeout_sec": 5, "unhealthy_threshold": 3, "healthy_threshold": 2, "eject_sec": 30, "host": "example" }, "host_header": "example" }'

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

Requires rules.edit.

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

Request Body required

Section titled “Request Body required ”
Media type application/json
object
record_id

Deprecated single-record scope. Prefer record_ids.

integer
nullable
record_ids

Scope the rule to these proxied records. Omit or send an empty array for a zone-wide rule. Every id must belong to this domain.

Array<integer>
enabled
boolean
default: true
priority
integer
default: 100
host_pattern
string
host_match_type

How host_pattern is matched. The empty string means “no host filter”, and is the only valid value when host_pattern is empty — the two fields are set and cleared together.

string
Allowed values: "" exact wildcard regex
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
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

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Rule created.

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
enabled
boolean
priority

Evaluation order; lower runs first. Defaults to 100.

integer
host_pattern

Optional hostname filter. Empty means the rule is not host-scoped.

string
host_match_type

How host_pattern is matched. The empty string means “no host filter”, and is the only valid value when host_pattern is empty — the two fields are set and cleared together.

string
Allowed values: "" exact wildcard regex
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
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
  }
}

400

Section titled “400 ”

Malformed body, an invalid field value, or record_ids containing a record that does not belong to this domain.

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 foreignRecords 
{
  "error": "record_ids do not belong to this domain"
}

401

Section titled “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"
}

403

Section titled “403 ”

The key is read-only, or the domain’s plan does not include this rule type or allows fewer rules of it than you already have.

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

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