Skip to content
nsin nsin nsin Docs

Add a domain

POST
/domains/
 
curl --request POST \
  --url https://api.nsin.ir/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

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type 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

Section titled “ Responses ”

200

Section titled “200 ”

Domain created.

Media type application/json
object
id
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

Section titled “400 ”

Invalid or unsupported domain name.

Media type 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

Section titled “401 ”

Missing, malformed, revoked or expired API key — or the owning account is inactive.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

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

403

Section titled “403 ”

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

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

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

409

Section titled “409 ”

The domain already exists on this or another account.

Media type 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

Section titled “429 ”

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

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

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