Skip to content
nsin docs
EN فا

Set the domain's custom pages

PUT
/domains/{domain}/custom-pages
 
curl --request PUT \
  --url https://api.nsin.ir/domains/example.com/custom-pages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "blocked": { "mode": "nsin", "html": "", "url": "" }, "waf": { "mode": "nsin", "html": "", "url": "" }, "rate_limit": { "mode": "custom", "html": "<h1>Slow down</h1>", "url": "" }, "maintenance": { "mode": "redirect", "html": "", "url": "https://status.example.net/", "enabled": true, "bypass_ips": [ "203.0.113.7", "198.51.100.0/24" ] } }'

Replaces the whole setting — send all four pages, since a page left out goes back to the NSIN page. Each page is one of three modes: nsin (the branded NSIN page), custom (your own HTML, at most 32 KiB, UTF-8) or redirect (a 302 to a full http:// or https:// URL). The field the mode does not use is kept as stored, so switching modes does not lose a draft.

While maintenance.enabled is true, every request to the domain is answered by the edge with 503 and never reaches the origin, except from maintenance.bypass_ips. A maintenance redirect must point at another domain.

Anything other than the defaults needs a plan with rules. The change reaches the edge with the next records sync. Requires domain.settings.

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
blocked

One page the edge serves itself.

object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
waf

One page the edge serves itself.

object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
rate_limit

One page the edge serves itself.

object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
maintenance
object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
enabled

While true, the edge answers every request with 503 and the origin is not reached.

boolean
bypass_ips

Addresses that still reach the site during maintenance — single IPs, CIDR prefixes or low-high ranges.

Array<string>
<= 100 items
Example 
{
  "blocked": {
    "mode": "nsin",
    "html": "",
    "url": ""
  },
  "waf": {
    "mode": "nsin",
    "html": "",
    "url": ""
  },
  "rate_limit": {
    "mode": "custom",
    "html": "<h1>Slow down</h1>",
    "url": ""
  },
  "maintenance": {
    "mode": "redirect",
    "html": "",
    "url": "https://status.example.net/",
    "enabled": true,
    "bypass_ips": [
      "203.0.113.7",
      "198.51.100.0/24"
    ]
  }
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The stored setting.

Media type application/json
object
blocked

One page the edge serves itself.

object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
waf

One page the edge serves itself.

object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
rate_limit

One page the edge serves itself.

object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
maintenance
object
mode

nsin — the branded NSIN page; custom — the HTML in html; redirect — a 302 to url.

string
default: nsin
Allowed values: nsin custom redirect
html

Your page, used in mode custom. At most 32 KiB, UTF-8.

string
url

Full http:// or https:// address, used in mode redirect. At most 2048 characters.

string
enabled

While true, the edge answers every request with 503 and the origin is not reached.

boolean
bypass_ips

Addresses that still reach the site during maintenance — single IPs, CIDR prefixes or low-high ranges.

Array<string>
<= 100 items
Example 
{
  "blocked": {
    "mode": "nsin"
  },
  "waf": {
    "mode": "nsin"
  },
  "rate_limit": {
    "mode": "nsin"
  },
  "maintenance": {
    "mode": "nsin"
  }
}

400

Section titled “400 ”

The body is not JSON, or a page is invalid: an unknown mode, custom with no HTML, redirect with no URL, HTML over 32 KiB or not UTF-8, a URL that is not a full http(s):// address or is over 2048 characters, a maintenance redirect onto the domain itself, more than 100 bypass addresses, or a bypass entry that is not an IP, a CIDR or a low-high range. The message names the page. Nothing is stored.

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": "rate_limit: add the HTML of your page"
}

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

402

Section titled “402 ”

The domain has no active plan and the setting is not the default.

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": "This domain does not have an active plan."
}

403

Section titled “403 ”

The key is read-only, your role on the domain lacks the required permission, or the domain’s plan does not include the feature.

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 it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

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