List DNS records

GET

/domains/{domain}/records/

const url = 'https://api.nsin.cloud/domains/example.com/records/';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url https://api.nsin.cloud/domains/example.com/records/ \
  --header 'Authorization: Bearer <token>'

All records of the domain, newest first.

Proxied records may carry origin_rules — origin route or origin pool rules that override where that record’s traffic actually goes, so the effective origin is not the record’s destination. Routes are listed before pools, mirroring edge precedence.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

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

Example

example.com

Responses

200

Record list.

application/json

Array

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

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

origin_rules

Absent when nothing overrides this record’s origin. Routes are listed before pools.

Array<object>

An enabled origin rule that overrides where a proxied record’s traffic goes, meaning the effective origin is not the record’s destination.

object

rule_id

integer

type

string

Allowed values: origin_route origin_pool

zone_wide

True when the rule applies to every proxied record of the domain.

boolean

dry_run

The rule is evaluated but not enforced.

boolean

Example

[
  {
    "name": "www",
    "original_name": "www.example.com.",
    "type": "A",
    "scheme": "Http",
    "origin_rules": [
      {
        "type": "origin_route"
      }
    ]
  }
]

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.

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

invalidKey

{
  "error": "invalid 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 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.

string

Example

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

429

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

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.

string

Examples

limited

{
  "error": "rate limit exceeded"
}