Set domain nameservers
PUThttps://api.instacloud.com/orgs/{orgId}/domains/{domainName}/nameservers
Token scope: account · org — read-only tokens refused (not a GET).
Delegate the domain to other nameservers (Cloudflare, Route 53, your own). They must already host the zone — some registries check before accepting the change. EVERY hostname this domain serves goes down with the move, because the records an attach published live in the registrar's zone: the answer marks them failed and names why. While the domain is delegated, attaching a hostname is refused for the same reason. (admin+)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | |
domainName | path | string | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
nameservers | string[] | yes | hostnames, in order; at least one |
Responses
200
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
domainName | string | yes | |
status | "registered" | "attaching" | "active" | "attach_failed" | "detached" | yes | detached: every service its hostnames named is gone — attach it again |
hostnames | object[] | yes | |
hostnames.hostname | string | yes | |
hostnames.state | "pending" | "attached" | "active" | "failed" | yes | |
hostnames.reason | string | no | |
hostnames.service | string | null | yes | the compute service this hostname serves; each hostname of a domain can serve a different one |
registeredAt | string | null | yes | |
expiresAt | string | null | yes | |
autorenew | boolean | yes | |
privacy | boolean | yes | |
locked | boolean | yes | the registrar transfer lock: while it is on, no other registrar can pull the domain away. Turn it off to move the domain out. What the last write reported, or what registration asked for — nothing reads it back |
nameservers | string[] | yes | what the registrar holds. Empty means never written — only a nameserver write fills it in |
delegated | boolean | yes | the zone is answered by nameservers InstaCloud cannot write to (custody `foreign`), so nothing published resolves and an attach is refused. A MANAGED delegation reads false: the platform still publishes there |
custody | "registrar" | "managed" | "foreign" | yes | who answers the domain's zone: the registrar's own nameservers, a managed InstaCloud zone (delegated, still platform-published), or somewhere the platform cannot write |
transferLockExpiresAt | string | null | yes | ICANN 60-day lock after registration: no transfer out before this, whatever `locked` says |
orderId | string | null | yes |
400
the registrar refused them — with its own sentence
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
403
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
404
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
502
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
503
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |