Skip to content
nsin nsin nsin Docs

Update a DNS record

PUT
/domains/{domain}/records/{recordId}
 
curl --request PUT \
  --url https://api.nsin.cloud/domains/example.com/records/1 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "destination": "example", "mx_priority": 1, "proxied": true, "captcha": true, "scheme": "Http", "port": 1, "host_header": "example", "monitor": true, "timeout": 1, "comment": "example" }'

Partial update — omitted fields keep their current value. Requires records.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
recordId
required
integer

Numeric id of the DNS record.

Request Body required

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

Every field is optional; omitted fields keep their current value.

object
name
string
destination
string
mx_priority
integer
<= 65535
proxied
boolean
captcha
boolean
scheme

Protocol the edge uses to reach the origin for a proxied record. Default follows the request’s own scheme; Auto probes.

string
Allowed values: Http Https Auto Default
port
integer
host_header
string
monitor
boolean
timeout
integer
comment
string
<= 1024 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Updated record.

Media type application/json
object
id
integer
name

Record name relative to the domain. @ is the apex.

string
original_name

The fully-qualified name, with trailing dot.

string
type
string
Allowed values: A AAAA CNAME ANAME NS TXT MX SRV PTR CAA TLSA SSHFP URI
destination

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.

string
dns_content

What is actually published in DNS. Equals the proxy IP for proxied records.

string
ttl

TTL in seconds.

integer
proxied

Route this hostname through the NSIN edge. Only A, AAAA, CNAME and ANAME may be proxied.

boolean
captcha

Challenge visitors before passing them to the origin.

boolean
editable

False for records NSIN manages on your behalf.

boolean
user_id
integer
domain_id
integer
scheme

Protocol the edge uses to reach the origin for a proxied record. Default follows the request’s own scheme; Auto probes.

string
Allowed values: Http Https Auto Default
port

Origin port for proxied records. Default: 443.

integer
host_header

Overrides the Host header (and SNI) sent to the origin.

string
monitor

Include this record in uptime monitoring.

boolean
dest_country

ISO country code of the destination, detected by NSIN.

string
timeout

Upstream timeout in seconds. Default: 15.

integer
mx_priority

Only meaningful for MX.

integer
<= 65535
comment

Free-form note.

string
<= 1024 characters
created_at
string format: date-time
updated_at
string format: date-time
Example 
{
  "name": "www",
  "original_name": "www.example.com.",
  "type": "A",
  "scheme": "Http"
}

400

Section titled “400 ”

Invalid value, or the record is not editable.

Media type application/json

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
error
required

Human-readable description of what went wrong.

string
code

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, not 403. 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 — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_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.

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

401

Section titled “401 ”

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.

Media type application/json

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
error
required

Human-readable description of what went wrong.

string
code

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, not 403. 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 — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_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.

string
Examples
Example invalidKey 
{
  "error": "invalid API key"
}

403

Section titled “403 ”

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.

Media type application/json

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
error
required

Human-readable description of what went wrong.

string
code

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, not 403. 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 — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_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.

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

404

Section titled “404 ”

Domain or record not found.

Media type application/json

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
error
required

Human-readable description of what went wrong.

string
code

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, not 403. 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 — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_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.

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 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
error
required

Human-readable description of what went wrong.

string
code

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, not 403. 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 — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_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.

string
Examples
Example limited 
{
  "error": "rate limit exceeded"
}