Set nameservers

PUT /v1/domain-purchases/:id/nameservers

Switches the domain's authoritative nameservers. Useful when the end-user wants to manage DNS at Cloudflare/Vercel/Route53 instead of going through us. Pass an empty array to revert to the registrar's default nameservers.

Heads-up: setting custom nameservers makes the registrar-side DNS records (managed via PUT /:id/dns) no longer authoritative. Whoever runs the new nameservers controls resolution. Restore the default nameservers ({ "nameservers": [] }) to make our DNS API meaningful again.

Request

# Switch to Cloudflare
curl -X PUT https://api.domainee.dev/v1/domain-purchases/f8a0c1b9-…/nameservers \
  -H "Authorization: Bearer $DOMAINEE_API_KEY" \
  -d '{
    "nameservers": [
      "albert.ns.cloudflare.com",
      "babette.ns.cloudflare.com"
    ]
  }'
 
# Or revert to default
curl -X PUT https://api.domainee.dev/v1/domain-purchases/f8a0c1b9-…/nameservers \
  -H "Authorization: Bearer $DOMAINEE_API_KEY" \
  -d '{ "nameservers": [] }'

Body parameters

Field	Required	Notes
nameservers	✅	Array of hostnames. 0–13 entries. Empty = revert to default.

Response — 200 OK

{
  "hostname": "janesbakery.com",
  "nameservers": ["albert.ns.cloudflare.com", "babette.ns.cloudflare.com"]
}

Errors

Code	Status	When
not_found	404	Purchase doesn't exist in this workspace.
bad_request	400	More than 13 nameservers, or invalid hostname.
Registrar error	502	Registrar refused — usually one of the nameservers doesn't resolve yet. Wait a few minutes after registering them upstream.

Notes

• Propagation can take up to 24 hours when switching nameservers (TLD glue records). Most users see the change in 5–15 minutes.
• If you switch to a custom NS host and that host doesn't know about the domain yet, you'll get an NXDOMAIN at lookup time. Register the domain at the new NS provider first.
• Anti-bricking: changing nameservers on a domain that's currently connected via POST /:id/connect will break the connection until you re-add the CNAME at the new NS provider. Re-call connect to re-do the wiring or do it manually at the new provider.