Create a DNS record
const url = 'https://api.nsin.cloud/domains/example.com/records/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","type":"A","destination":"example","mx_priority":1,"proxied":false,"captcha":false,"scheme":"Http","port":443,"host_header":"example","monitor":true,"dest_country":"example","timeout":15,"comment":"example"}'};
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/records/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "type": "A", "destination": "example", "mx_priority": 1, "proxied": false, "captcha": false, "scheme": "Http", "port": 443, "host_header": "example", "monitor": true, "dest_country": "example", "timeout": 15, "comment": "example" }'Creates one record and publishes it to the DNS zone.
Setting proxied: true routes the hostname through the NSIN edge: the
published DNS answer becomes the NSIN proxy IP and destination becomes
the origin the edge connects to. Only A, AAAA, CNAME and ANAME
can be proxied. Requires records.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
Name relative to the domain. Use @ for the apex.
IP address, hostname or text content.
Protocol the edge uses to reach the origin for a proxied record.
Default follows the request’s own scheme; Auto probes.
Responses
Section titled “ Responses ”Record created.
object
Record name relative to the domain. @ is the apex.
The fully-qualified name, with trailing dot.
The record’s value. For a proxied record this is the origin the
edge connects to, and the published DNS answer is the NSIN proxy IP
instead — see dns_content.
What is actually published in DNS. Equals the proxy IP for proxied records.
TTL in seconds.
Route this hostname through the NSIN edge. Only A, AAAA, CNAME
and ANAME may be proxied.
Challenge visitors before passing them to the origin.
False for records NSIN manages on your behalf.
Protocol the edge uses to reach the origin for a proxied record.
Default follows the request’s own scheme; Auto probes.
Origin port for proxied records. Default: 443.
Overrides the Host header (and SNI) sent to the origin.
Include this record in uptime monitoring.
ISO country code of the destination, detected by NSIN.
Upstream timeout in seconds. Default: 15.
Only meaningful for MX.
Free-form note.
Example
{ "name": "www", "original_name": "www.example.com.", "type": "A", "scheme": "Http"}Invalid record — bad type, malformed destination, or a value the zone rejects.
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"}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 the required
permission, the domain’s plan does not include the feature, or the
account that owns the key has been deactivated — that last one carries
code: account_suspended and can arrive on any endpoint, including ones
that document no 403 of their own.
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 it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.
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"}The domain is disabled, or a conflicting record already exists.
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"}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"}