Update a DNS record

PUT

/domains/{domain}/records/{recordId}

const url = 'https://api.nsin.ir/domains/example.com/records/1';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","destination":"example","mx_priority":1,"ttl":120,"proxied":true,"captcha":true,"scheme":"Http","port":1,"host_header":"example","host_header_mode":"own","monitor":true,"timeout":1,"comment":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Partial update — omitted fields keep their current value. The type cannot be changed. The same rules as creating apply to the new values (see POST .../records/); DNS is republished, a proxied change reaches the edge at once, and on an external-DNS domain the edge check runs again in the background. Records NSIN manages (editable: false — gateway records, locked Email Routing records) cannot be changed here. Requires records.edit.

Authorizations

bearerAuth
apiKeyAuth

Parameters

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

application/json

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

object

name

string

destination

New value — see destination on Record.

string

mx_priority

MX priority. MX only.

integer

<= 65535

ttl

Seconds resolvers may cache this record. Forced to 120 while proxied is true — a proxied record answers with our edge addresses, and traffic can only be moved between edges as fast as the slowest resolver still holding the old answer.

integer

default: 120 >= 1 <= 604800

proxied

See proxied on RecordCreate.

boolean

captcha

Challenge visitors before passing them to the origin.

boolean

scheme

Protocol the edge uses to reach the origin of a proxied record.

Https — TLS to port (443 when the port is unset or out of range).
Http — plain HTTP to port (80 when unset or out of range).
Auto — HTTPS on 443 first, falling back to plain HTTP. The port is always 443.
Default — accepted on input, and so are an empty or unrecognised value, but stored as Auto with port 443: a record never reads back as Default.

string

Allowed values: Http Https Auto Default

port

See port on RecordCreate.

integer

host_header

See host_header on RecordCreate. An empty string removes the override.

string

host_header_mode

See host_header_mode on RecordCreate.

string

Allowed values: own target

monitor

Include this record in uptime monitoring.

boolean

timeout

Origin wait before 504, in seconds. Max 1800 (30 minutes).

integer

>= 1 <= 1800

comment

Free-form note. An empty string removes it.

string

<= 1024 characters

Responses

200

Updated record.

application/json

object

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

managed_by

The platform feature that owns this record, or empty for a record you created. email_routing marks the MX, SPF and DKIM rows Email Routing publishes; they are removed by disabling routing, never through the record endpoints (which refuse them while locked).

string

user_id

integer

domain_id

integer

scheme

Protocol the edge uses to reach the origin of a proxied record.

Https — TLS to port (443 when the port is unset or out of range).
Http — plain HTTP to port (80 when unset or out of range).
Auto — HTTPS on 443 first, falling back to plain HTTP. The port is always 443.
Default — accepted on input, and so are an empty or unrecognised value, but stored as Auto with port 443: a record never reads back as Default.

string

Allowed values: Http Https Auto Default

port

Origin port for proxied records: 443 for Auto, otherwise as set (default 443 for Https, 80 for Http).

integer

host_header

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

string

host_header_mode

Which name a proxied CNAME/ANAME sends to its origin as the Host header (and SNI) when host_header is empty: empty — the record’s own hostname (the default); target — the hostname it points at.

string

Allowed values: "" target

gateway_preset_id

The gateway this record was created for, or null for a record you made. A gateway record is not editable here; rename or remove it through the gateway endpoints.

integer | null

gateway_allowed_hosts

Gateway records only: a JSON array, as a string, of the other hostnames the gateway’s service links to. The edge serves them under /_nsin/<host>/ on the gateway hostname.

string

gateway_rewrite_urls

Gateway records only — whether the edge rewrites URLs in responses to go through the gateway.

boolean

monitor

Include this record in uptime monitoring.

boolean

timeout

How long an edge node waits for the origin to start responding before returning 504, in seconds. Default 60, maximum 1800 (30 minutes). Only applies to proxied records.

integer

default: 60 >= 1 <= 1800

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

deleted_at

Always null — deleted records are never returned.

string | null format: date-time

edge_status

External-DNS domains, proxied records only. Whether the name resolves to NSIN’s edge, as last checked: ok — every address it resolves to is ours; miss — it resolves elsewhere, only partly to us, or not at all; error — the first lookup failed and nothing is known yet. Absent until the first check, and always absent on a managed-DNS domain.

string

Allowed values: ok miss error

edge_via

How an ok record reaches NSIN: through the CNAME target (cname), by publishing our address directly (a), or proxy — DNS points at another CDN or proxy, but that service forwards to NSIN and the edge is serving the host (judged from the last 24h of request logs). A CNAME keeps working when our addresses change; an A record does not.

string

Allowed values: cname a proxy

edge_detail

What the name actually resolves to, for display.

string

edge_checked_at

string format: date-time

Example

{
  "name": "www",
  "original_name": "www.example.com.",
  "type": "A",
  "scheme": "Http",
  "host_header_mode": "",
  "timeout": 60,
  "edge_status": "ok",
  "edge_via": "cname"
}

400

Malformed body or an invalid value (see POST .../records/).

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

401

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

402

Setting host_header on a domain with no active plan.

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

403

Read-only key, insufficient role, the record is not editable, or a new host_header on a plan without the Host-header override feature.

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

Domain or record not found.

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

409

The domain is disabled or banned.

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

The key exceeded its request budget (300 requests per minute by default).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}

502

The DNS servers refused the write; retry in a moment.

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

Update a DNS record

Authorizations

Parameters

Path Parameters

Example

Request Body required

Responses

200

Example

400

Example

401

Examples

402

Example

403

Example

404

Example

409

Example

429

Examples

502

Example

Request Body^required