Host (glue) records

View as Markdown Open in Claude Open in ChatGPT

A host record is needed when you run a name server that lives under the domain it serves — ns1.apiname.com answering for apiname.com. Resolvers cannot look that up without a circular dependency, so the registry publishes its IP addresses as glue.

Two terms you will meet in the errors:

In-bailiwick — the host name is a subdomain of the domain it serves. Most registries only accept glue for in-bailiwick hosts. Anything else gives Dna.DomainService:Dns:10019.
Host object support — registries differ in how they model name servers. The catalogue field isHostObjectAccepted tells you, and isGlueRecordAllowed says whether glue is accepted at all.

The two models, and why it matters to you

There are two ways a registry can represent a name server that lives under your domain. Which one applies changes what you get back from GET /domains/info, so it is worth understanding before you build a UI around it.

`isHostObjectAccepted`	What happens to `ns1.apiname.com`
true	It becomes a host object — an independent record at the registry with its own name and IP addresses. It can be created, renamed, re-addressed and deleted on its own, and it can be shared by several domains.
false	No host object is created. The name server stays attached to the domain as a glue record: the name and its IP travel with the domain’s own record rather than existing separately.

POST `/api/v1/domains/dns/host`

Creates a host record with its IP addresses.

Request

{
  "domainName": "apiname.com",
  "hostName": "ns1.apiname.com",
  "ipAddresses": [
    { "ipAddress": "203.0.113.10", "ipVersion": "v4" },
    { "ipAddress": "2001:db8::10", "ipVersion": "v6" }
  ]
}

Field	Required	Notes
`domainName`	required	Maximum 63 characters.
`hostName`	required	Full host name, maximum 100 characters. Normally must be a subdomain of `domainName`.
`ipAddresses`	required	At least one. No duplicates.
`ipAddresses[].ipAddress`	required	IPv4 or IPv6 literal.
`ipAddresses[].ipVersion`	required	`v4` or `v6`. Case does not matter.

Response — 204, no body

PUT `/api/v1/domains/dns/host` · DELETE `/api/v1/domains/dns/host`

Rename a host and/or replace its IP addresses, or delete it.

PUT — change the IP addresses

{
  "domainName": "apiname.com",
  "hostName": "ns1.apiname.com",
  "ipAddresses": [
    { "ipAddress": "203.0.113.20", "ipVersion": "v4" }
  ]
}

PUT — rename and re-address in one call

{
  "domainName": "apiname.com",
  "hostName": "ns1.apiname.com",
  "newHostName": "dns1.apiname.com",
  "ipAddresses": [
    { "ipAddress": "203.0.113.20", "ipVersion": "v4" }
  ]
}

ipAddresses is the complete replacement set. Omit newHostName to keep the current name.

DELETE

{
  "domainName": "apiname.com",
  "hostName": "ns1.apiname.com"
}