# DNS records

> How zones on our name servers work: record sets, zone creation on first use, publishing, propagation and name matching.

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](https://www.domainnameapi.com/docs/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:

```text
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

:::danger[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. |

:::tip[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.