nsindocs Search the docs⌘K
API
  1. Docs
  2. API reference
  3. Custom Name Servers

Turn on custom name servers

posthttps://api.nsin.ir/domains/{domain}/custom-ns/enable

Auth: Authorization: Bearer nsin_… or X-Api-Key: nsin_… — see API keys.

Creates one locked A record per name, pointing at an NSIN name server. Nothing changes for visitors until you set the names AND their IPs (from names) at your registrar. Sending other names renames them, but only while the registrar does not use them yet (409 otherwise). Sending the same names again changes nothing, and cancels a turn-off in progress. 409 also when a record already uses one of the names (field: names). Requires records.edit.

Path parameters

  • domainstringrequiredpath

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

Request body

Content type: application/json

  • namesarray of string

    The first label of each name. Default ["ns1", "ns2"].

Responses

200Turned on; the state.

Content type: application/json

  • availableboolean

    The platform offers custom name servers.

  • plan_allowsboolean

    The domain's plan includes them (Enterprise).

  • can_enableboolean

    The domain is active on NSIN's name servers.

  • suffixstring

    What follows each name

  • labelsarray of string

    The current names' first labels

  • statestring
    One of: "" "on" "turning_off"
  • statusstring

    waiting: the registrar still shows NSIN's names. working: it shows yours with the right IPs. wrong_ip: it has another IP for the hosts in wrong_ip. no_ip: it has the names but no IPs. other: something else. checking: no answer yet.

    One of: "waiting" "working" "wrong_ip" "no_ip" "other" "checking"
  • namesarray of object
    Item fields
    • hoststring
    • ipstring
  • wrong_iparray | null
  • old_nsarray of string

    The names to put back at the registrar when turning off.

  • min_namesinteger
  • max_namesinteger
json
{
  "available": true,
  "plan_allows": true,
  "can_enable": true,
  "suffix": "string",
  "labels": [
    "string"
  ],
  "state": "",
  "status": "waiting",
  "names": [
    {
      "host": "ns1.example.com",
      "ip": "198.51.100.10"
    }
  ],
  "wrong_ip": [
    "string"
  ],
  "old_ns": [
    "string"
  ],
  "min_names": 0,
  "max_names": 0
}
400A name is not a single DNS label, is used twice, or there are fewer than 2 or more than 5.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
401Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "invalid API key"
}
403The key is read-only, your role on the domain lacks the required permission, or the domain's plan does not include the feature.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
404No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
409The domain is not active on NSIN, a record uses one of the names, or the registrar already uses the current names.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
429The key exceeded its request budget (300 requests per minute by default).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "rate limit exceeded"
}
502The records could not be published; nothing was changed. Try again.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
503Custom name servers are not available on this platform yet.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

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

Example request

bash
curl -X POST "https://api.nsin.ir/domains/example.com/custom-ns/enable" \
  -H "Authorization: Bearer $NSIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "ns1",
    "ns2"
  ]
}'
esc