Create a cache rule
const url = 'https://api.nsin.cloud/domains/example.com/rules/cache/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"record_id":1,"record_ids":[1],"enabled":true,"priority":100,"host_pattern":"example","host_match_type":"","action_mode":"enforce","path_match_type":"wildcard","path_includes":["example"],"path_excludes":["example"],"ttl_sec":1,"refresh_sec":1,"with_qs":true,"scope":"default","bypass_authorization":true,"bypass_set_cookie":true,"respect_client_no_store":true,"respect_origin_cache_control":true,"respect_origin_max_age":true,"bypass_wp_admin":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.nsin.cloud/domains/example.com/rules/cache/ \ --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", "path_match_type": "wildcard", "path_includes": [ "example" ], "path_excludes": [ "example" ], "ttl_sec": 1, "refresh_sec": 1, "with_qs": true, "scope": "default", "bypass_authorization": true, "bypass_set_cookie": true, "respect_client_no_store": true, "respect_origin_cache_control": true, "respect_origin_max_age": true, "bypass_wp_admin": true }'Decides what the edge caches, for how long, and which safety bypasses apply. A domain may hold several cache rules with different tradeoffs; each is self-contained.
Requires rules.edit.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The domain name (for example example.com) — not a numeric id.
Example
example.comRequest Body required
Section titled “Request Body required ”object
Deprecated single-record scope. Prefer 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.
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.
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.
How path_includes and path_excludes are interpreted.
Paths the rule applies to. Defaults to ["/*"] — everything.
Paths carved back out of path_includes.
How long an entry stays fresh, in seconds. 0 uses the default.
Background refresh interval in seconds — the entry is re-fetched
this often while still being served. 0 disables it.
Include the query string in the cache key. Off means ?a=1 and ?a=2 share one entry.
What the rule caches among the paths it already matches.
default— static assets only, chosen by file extension.everything— every cacheable response, HTML included.
There is no “custom” scope: narrow what you cache by scoping
path_includes instead.
Skip caching requests that carry an Authorization header. Leave on
unless you are certain the response is not user-specific.
Skip caching responses that set a cookie. Turning this off can serve one visitor’s session to another — only do it for responses you know are anonymous.
Honour Cache-Control: no-store from the client.
Honour the origin’s Cache-Control directives.
Use the origin’s max-age instead of ttl_sec.
Never cache WordPress admin and login paths.
Responses
Section titled “ Responses ”Rule created.
object
Deprecated single-record scope. Prefer record_ids. Absent for
zone-wide rules.
The proxied DNS records this rule applies to. Empty or absent means zone-wide — every proxied record of the domain.
Evaluation order; lower runs first. Defaults to 100.
Optional hostname filter. Empty means the rule is not host-scoped.
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.
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.
How path_includes and path_excludes are interpreted.
Paths the rule applies to. Defaults to ["/*"] — everything.
Paths carved back out of path_includes.
How long an entry stays fresh, in seconds. 0 uses the default.
Background refresh interval in seconds — the entry is re-fetched
this often while still being served. 0 disables it.
Include the query string in the cache key. Off means ?a=1 and ?a=2 share one entry.
What the rule caches among the paths it already matches.
default— static assets only, chosen by file extension.everything— every cacheable response, HTML included.
There is no “custom” scope: narrow what you cache by scoping
path_includes instead.
Skip caching requests that carry an Authorization header. Leave on
unless you are certain the response is not user-specific.
Skip caching responses that set a cookie. Turning this off can serve one visitor’s session to another — only do it for responses you know are anonymous.
Honour Cache-Control: no-store from the client.
Honour the origin’s Cache-Control directives.
Use the origin’s max-age instead of ttl_sec.
Never cache WordPress admin and login paths.
Example
{ "type": "cache", "host_match_type": "", "action_mode": "enforce", "path_match_type": "wildcard", "scope": "default", "bypass_authorization": true, "bypass_set_cookie": true, "respect_client_no_store": true, "respect_origin_cache_control": true, "respect_origin_max_age": true, "bypass_wp_admin": true}Malformed body, an invalid field value, or record_ids containing a
record that does not belong to this domain.
The error shape used by every endpoint. error is always present. code
is present only on the failures that have one — do not require it, and do
not parse error to recover it.
object
Human-readable description of what went wrong.
Stable machine-readable reason. Present on some failures only; the
wording of error may change, this will not.
account_suspended—403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.domain_disabled—409, not403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.managed_by_reseller—403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.invite_email_mismatch—403fromPOST /invites/{token}/accept. The invitation was addressed to a different email; the body also carriesinvited_email, masked.
A panel session — not an API key — can additionally see
session_check_failed on a 503, which means the session could not
be verified, not that it is invalid. Retry it; do not discard the
token.
Examples
{ "error": "record_ids do not belong to this domain"}Missing, malformed, revoked or expired API key, or a key whose owning
user row is gone. A key whose owning account has merely been deactivated
is not this: that is 403 with code: account_suspended, because the
credential itself is intact and re-issuing it changes nothing.
The error shape used by every endpoint. error is always present. code
is present only on the failures that have one — do not require it, and do
not parse error to recover it.
object
Human-readable description of what went wrong.
Stable machine-readable reason. Present on some failures only; the
wording of error may change, this will not.
account_suspended—403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.domain_disabled—409, not403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.managed_by_reseller—403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.invite_email_mismatch—403fromPOST /invites/{token}/accept. The invitation was addressed to a different email; the body also carriesinvited_email, masked.
A panel session — not an API key — can additionally see
session_check_failed on a 503, which means the session could not
be verified, not that it is invalid. Retry it; do not discard the
token.
Examples
{ "error": "invalid API key"}The key is read-only, your role on the domain lacks rules.edit (a
viewer has domain.view and nothing more), or the domain’s plan does
not include this rule type or allows fewer rules of it than you already
have.
The error shape used by every endpoint. error is always present. code
is present only on the failures that have one — do not require it, and do
not parse error to recover it.
object
Human-readable description of what went wrong.
Stable machine-readable reason. Present on some failures only; the
wording of error may change, this will not.
account_suspended—403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.domain_disabled—409, not403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.managed_by_reseller—403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.invite_email_mismatch—403fromPOST /invites/{token}/accept. The invitation was addressed to a different email; the body also carriesinvited_email, masked.
A panel session — not an API key — can additionally see
session_check_failed on a 503, which means the session could not
be verified, not that it is invalid. Retry it; do not discard the
token.
Example
{ "error": "read-only API key"}No such domain, or you hold no role on it at all.
It no longer means “your role is too low”. The rules endpoints resolve
access through the shared domain guard, which answers 403 when the
caller can see the domain but lacks rules.edit, and 409 with
code: domain_disabled when the domain is switched off and the request
is a write. Reading is open to every role, so a GET can only fail here.
The error shape used by every endpoint. error is always present. code
is present only on the failures that have one — do not require it, and do
not parse error to recover it.
object
Human-readable description of what went wrong.
Stable machine-readable reason. Present on some failures only; the
wording of error may change, this will not.
account_suspended—403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.domain_disabled—409, not403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.managed_by_reseller—403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.invite_email_mismatch—403fromPOST /invites/{token}/accept. The invitation was addressed to a different email; the body also carriesinvited_email, masked.
A panel session — not an API key — can additionally see
session_check_failed on a 503, which means the session could not
be verified, not that it is invalid. Retry it; do not discard the
token.
Examples
{ "error": "domain not found"}The key exceeded its request budget (300 requests per minute by default).
The error shape used by every endpoint. error is always present. code
is present only on the failures that have one — do not require it, and do
not parse error to recover it.
object
Human-readable description of what went wrong.
Stable machine-readable reason. Present on some failures only; the
wording of error may change, this will not.
account_suspended—403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.domain_disabled—409, not403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.managed_by_reseller—403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.invite_email_mismatch—403fromPOST /invites/{token}/accept. The invitation was addressed to a different email; the body also carriesinvited_email, masked.
A panel session — not an API key — can additionally see
session_check_failed on a 503, which means the session could not
be verified, not that it is invalid. Retry it; do not discard the
token.
Examples
{ "error": "rate limit exceeded"}