DNS records

Manage the contents of a DNS zone hosted on our name servers — A, AAAA, CNAME, MX, TXT, SRV, CAA and the rest. For delegation and glue, see Name servers.

Three things to understand first

1 · Records are grouped by name and type

A record set is everything sharing the same name and type. All values in a set share one TTL. There is no per-record TTL and no record ID — a record is identified by its value.

So www with two A values is one record set with two values, not two records:

www.apiname.com.  A  3600  203.0.113.10
                        203.0.113.11    ← same set, same TTL

This is why DELETE asks you for the value you want gone rather than an ID, and why PUT replaces an entire set.

2 · The zone is created on first use

There is no “create zone” call. The first successful POST for a domain creates the zone, seeded with a default SOA record and our name servers. A GET on a domain with no zone returns an empty array — not an error.

3 · Writing a record is not enough to make it resolve

The step everyone forgets

Records only answer queries if the domain is delegated to our name servers. Until then your records sit in our system answering nothing.

1. POST /domains/zones — write the records.
2. POST /domains/zones/apply — delegate the domain to us.
3. Wait for the parent zone’s TTL — up to 48 hours on a first switch.
4. Individual record changes after that propagate in one record TTL.

How long until changes are live?

Change	Visible when
Writing a record in our DNS	Immediately. Served by our name servers as soon as the call returns. No publication queue.
Changing delegation (/apply)	Seconds at the registry, but resolvers cache the old name servers for the parent zone’s TTL — 1 to 48 hours depending on the extension.
Changing a record in an already-delegated zone	One record TTL, which you control.
Adding a name that did not exist before	Up to 5 minutes for resolvers that already looked it up and cached the “does not exist” answer.

Planning a change with no downtime

1. Lower the TTL on the record to 300 and wait one old TTL.
2. Make the real change. It now propagates in 5 minutes.
3. Verify, then raise the TTL back to 3600 or higher.

How we match the name you send

Names are normalised to the full form. For zone apiname.com:

You send	Record created at
"" or "@"	apiname.com. — the apex
"www"	www.apiname.com.
"www.apiname.com"	www.apiname.com.
"mail.eu"	mail.eu.apiname.com.
"örnek"	xn--rnek-hra.apiname.com. — converted automatically

When matching a value for update or delete, we are forgiving: extra whitespace and a trailing dot are ignored, Unicode host names are converted, and matching is case-insensitive for host-name-bearing types. TXT and CAA values are case-sensitive, but surrounding quotes are ignored — so you can send v=spf1 -all or "v=spf1 -all" and either matches.