Add a domain

POST

/domains/

const url = 'https://api.nsin.cloud/domains/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example.com","dns_mode":"managed"}'
};

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/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example.com", "dns_mode": "managed" }'

Registers a domain on your account.

dns_mode: managed (default) — NSIN hosts the zone. The domain starts in pending until its nameservers point at the NSIN set returned by GET /domains/ns-sets, then flips to active automatically.
dns_mode: external — you keep DNS elsewhere. The domain starts in unverified and you prove ownership with the TXT record from the verification block, then call POST /domains/{domain}/verify.

Existing records are scanned and imported in the background for managed domains.

Authorizations

bearerAuth
apiKeyAuth

Request Body^required

application/json

object

name

required

The domain to add, without scheme or trailing dot.

string

dns_mode

string

default: managed

Allowed values: managed external

Responses

200

Domain created.

application/json

object

integer

name

string

status

pending — managed domain waiting for its nameservers to point at NSIN.
unverified — external-DNS domain waiting for its TXT verification record.
active — serving.
moved — delegation has left NSIN; the domain keeps serving during a grace window.
disabled — not serving; re-enable with POST /domains/{domain}/enable.
banned — administratively blocked.

string

Allowed values: pending unverified active moved disabled banned

dns_mode

managed — NSIN hosts the DNS zone. external — you host DNS elsewhere and prove ownership with a TXT record.

string

Allowed values: managed external

user_id

Id of the owning user.

integer

verification_started_at

string format: date-time

cache_l2_max_gb

Per-domain cap on disk (L2) cache size, in GB.

integer

cache_l2_ttl_days

How long a disk-cache entry may live, in days. Maximum 7.

integer

>= 1 <= 7

cache_cap_mb

Largest response body NSIN will buffer and cache, in MB. Bigger responses stream straight from origin and are never cached. The selectable ceiling depends on the domain’s plan.

integer

Allowed values: 128 256 512 2048 4096

developer_mode_until

While set and in the future, the edge bypasses cache reads and writes for this domain. Absent when developer mode is off.

string format: date-time

pending_since

string format: date-time

moved_since

string format: date-time

next_check_at

When the background nameserver checker will next look at this domain.

string format: date-time

last_manual_ns_check_at

Last user-triggered nameserver check; these are limited to one per hour.

string format: date-time

sec_no_sniff

Send X-Content-Type-Options: nosniff. Off by default — it can break an origin that mislabels asset MIME types.

boolean

sec_referrer_policy

Send Referrer-Policy: strict-origin-when-cross-origin.

boolean

sec_strip_headers

Strip origin fingerprint headers from responses.

boolean

markdown_for_agents

Serve a Markdown rendering of eligible HTML pages to clients sending Accept: text/markdown. Requires an active plan.

boolean

outage_alerts

Notify the owner when a subdomain suffers a sustained origin outage.

boolean

uptime_threshold_pct

Per-minute origin-error percentage that counts as “down”.

integer

>= 50 <= 100

uptime_window_min

Minutes the domain must stay down before an incident opens.

integer

>= 2 <= 60

uptime_min_requests

Minimum origin-eligible requests in the window — the traffic floor below which no incident opens.

integer

uptime_min_active_min

Minimum populated one-minute buckets required in the window.

integer

uptime_recover_min

Consecutive clear minutes before an incident resolves.

integer

suspended

Paused for billing. The edge refuses the domain’s TLS handshake, so visitors get a connection error. Clears automatically once the wallet is no longer negative.

boolean

suspended_at

string format: date-time

created_at

string format: date-time

updated_at

string format: date-time

verification

The TXT record to publish to prove ownership of an external-DNS domain.

object

host

Name to create the TXT record at.

string

type

string

Allowed value: TXT

value

Exact TXT value to publish.

string

verified

boolean

expires_at

string format: date-time

seconds_remaining

integer

nsin_ns

The canonical (first) accepted nameserver set.

Array<string>

nsin_ns_sets

Every accepted nameserver set. The delegation must match exactly one set in full — sets cannot be mixed.

Array<Array<string>>

current_ns

The nameservers currently observed in the parent zone.

Array<string>

my_role

Your role on a domain. owner is implicit for the domain’s creator and for global admins; the other three are grantable via sharing.

string

Allowed values: owner admin editor viewer

my_permissions

Array<string>

Allowed values: domain.view domain.settings domain.delete records.edit rules.edit cache.edit ssl.manage analytics.view billing members.manage

ns_check_interval_seconds

How often the background checker re-checks the delegation.

integer

Example

{
  "name": "example.com",
  "status": "pending",
  "dns_mode": "managed",
  "cache_cap_mb": 128,
  "verification": {
    "type": "TXT"
  },
  "my_role": "owner",
  "my_permissions": [
    "domain.view"
  ]
}

400

Invalid or unsupported domain name.

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

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.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

403

The key is read-only and this endpoint is a write. Read-only keys may only issue GET, HEAD and OPTIONS.

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

readOnly

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

409

The domain already exists on this or another account.

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

Add a domain

Authorizations

Request Body required

Responses

200

Example

400

Example

401

Examples

403

Examples

409

Example

429

Examples

Request Body^required