Records through the API

Records live under their zone. All four endpoints need a key with dns:read or dns:write.

The endpoints

Listing

GET /api/v1/dns/zones/example.com/records

Returns every record in the zone with its id, name, type, TTL and value, plus a count.

The apex NS records are the platform's, not yours. They are re-asserted on every sync, so a change to them through the API is undone within seconds — declining to edit them is kinder than accepting a change and losing it.

Creating

POST /api/v1/dns/zones/example.com/records
{ "name": "www", "type": "A", "ttl": 3600, "content": "203.0.113.10" }

The record type has to be one your plan allows — see record types by plan. A type your plan does not include is refused with a clear error rather than silently ignored.

Validation is the same as the form's. A CNAME at the apex is refused; an MX pointing at an IP address is refused; a hostname that is actually an IP is refused. Those are not arbitrary: each produces a record resolvers reject.

Updating

PATCH /api/v1/dns/zones/example.com/records/{id}
{ "content": "203.0.113.20" }

You need the record's id, which means listing first. That is deliberate rather than an omission: a zone can hold several records with the same name and type — two A records at www, four MX records at the apex — so a name-and-type pair does not identify one record. Updating by name would make "change the A record for www" ambiguous the moment a second one exists.

Send only the fields you are changing.

Deleting

DELETE /api/v1/dns/zones/example.com/records/{id}

Same reasoning: by id, because the alternative deletes more than you meant.

When the change is live

A write through the API is an ordinary change. It is applied to the primary, replicated to the other nameservers, and recorded in the zone's history exactly as an edit in the portal would be — so Time Machine can roll back a bad automated change the same way.

What it does not do is expire caches. A record with a 24-hour TTL keeps serving the old value for up to a day, however it was changed. See publishing and when a change is really live.

Related

• Zones through the API
• API errors, limits and retries

Last reviewed 2026-09-16.