Skip to content

Knowledgebase

Register and maintain private nameserver hosts through the API

domain-nexus, development

Private nameserver hosts record the registry-side hostname and address information needed for supported branded nameservers. They are separate from ordinary A/AAAA records in your DNS zone and from the domain's delegated nameserver list. Prepare all required layers for a working service.

01 Create a host under an owned domain

Method Resource Scope Idempotency-Key
GET /v2/domains/{domainId}/private-nameservers domains:read Not required by this route
POST /v2/domains/{domainId}/private-nameservers domains:private-ns Required
PATCH /v2/domains/{domainId}/private-nameservers/{hostId} domains:private-ns Required
DELETE /v2/domains/{domainId}/private-nameservers/{hostId} domains:private-ns Required
  1. List the domain's existing private nameserver hosts to avoid creating a duplicate.
  2. Confirm the hostname is under the owned domain and that the nameserver actually serves the intended DNS zones.
  3. POST the full hostname with at least one address in ipv4 or ipv6.
  4. Track the returned operation and read the resulting host record.
  5. Publish matching forward DNS address records and set the intended registrar delegation through their separate workflows.

A documentation example is:

Structured data example
{
  "hostname": "ns1.example.com",
  "ipv4": ["192.0.2.10"],
  "ipv6": ["2001:db8::10"]
}

Replace all example values with the authorised live nameserver and its addresses.

How do updates work?

PATCH the returned hostId and include the current row_version where available. Omitted hostname or address fields are retained. This build also accepts PUT as a compatibility alias for that PATCH behaviour; it is not a separate replace-everything contract.

Why can deletion be rejected?

The registry may protect a host still used by dependent domains. Move those delegations first and verify the replacement service before deleting the old host. Removing its ordinary A record alone does not remove the registry dependency.

After an address migration, compare parent glue and authoritative address data as well as the nameserver's actual reachability. Keep both old and new service arrangements available for the planned transition where required. A successful host operation does not prove the DNS daemon, firewall or every customer zone is ready.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support