Create a DNS record

POST

/domains/{domain}/records/

const url = 'https://api.nsin.ir/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,"ttl":120,"proxied":false,"captcha":false,"scheme":"Http","port":1,"host_header":"example","host_header_mode":"own","monitor":true,"timeout":60,"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.ir/domains/example.com/records/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "type": "A", "destination": "example", "mx_priority": 1, "ttl": 120, "proxied": false, "captcha": false, "scheme": "Http", "port": 1, "host_header": "example", "host_header_mode": "own", "monitor": true, "timeout": 60, "comment": "example" }'

Creates one record and publishes it to the DNS zone (on a managed domain). A name and type that already exist are refused — except TXT, where many records may share a name.

Setting proxied: true routes the hostname through the NSIN edge: the published DNS answer becomes the NSIN proxy IP, destination becomes the origin the edge connects to, and the TTL is fixed at 120. Only A, AAAA, CNAME and ANAME can be proxied, a hostname can carry only one proxied origin, and the origin must be an address the edge will connect to (not a private, reserved or NSIN address). Proxied records are pushed to the edge at once and a certificate covering the name is requested if needed.

Requires records.edit; the record counts against the plan’s record allowance, and host_header needs a plan with the Host-header override feature.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

Request Body^required

application/json

object

name

required

Name relative to the domain. Use @ for the apex.

string

type

required

string

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

destination

required

IP address, hostname or text content.

string

mx_priority

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

Route the name through the NSIN edge. Ignored (the record is created unproxied) for types other than A, AAAA, CNAME and ANAME. The origin must be an address the edge accepts, and a name can have only one proxied origin.

boolean

captcha

Challenge visitors before passing them to the origin. Forced off for DNS-only types.

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

Origin port. Default 443 (80 for Http); always 443 with Auto.

integer

host_header

Host header (and SNI) to send to the origin instead of the record’s name. Must be inside this domain or another active domain of the same owner. Needs a plan with the Host-header override feature.

string

host_header_mode

CNAME/ANAME only: send the record’s own name (own, the default) or the target it points at (target) as the Host header. Cannot be combined with host_header, and target is refused when the target is hosted on NSIN under another account.

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

default: 60 >= 1 <= 1800

comment

Free-form note, trimmed.

string

<= 1024 characters

Responses

200

Record created.

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

Invalid record — a missing or disallowed type, a bad name or destination for the type, TTL outside 1–604800, timeout outside 1–1800, a comment over 1024 characters, a host_header outside the domain and the owner’s other active domains, an invalid host_header_mode (field: host_header_mode), a name and type that already exist (record exists — for TXT, MX, NS, SRV, CAA, TLSA, SSHFP and URI several records may share a name, and only the same value twice is refused), a second proxied origin for the same hostname, or a proxied origin the edge refuses (code: proxy_origin_rejected, field: destination).

application/json

object

error

required

Human-readable description of what went wrong.

string

field

The request field at fault, when known.

string

code

Present when a proxied origin is refused.

string

Allowed values: proxy_origin_rejected

Example

{
  "error": "read-only API key",
  "code": "proxy_origin_rejected"
}

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

The domain has no active plan, so no records can be added.

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 plan’s record allowance is used up, or host_header is set 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

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

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. Nothing was published; 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"
}

Create 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