DNS zone and record API
Verify zones, publish record sets, and inspect authoritative publication revisions.
The DNS API manages zone ownership and record sets. A record mutation changes authoritative configuration; recursive resolver and application caches retain their own TTL behavior.
Add a zone
/organizations/{organization_id}/projects/{project_id}/dns-zonesCreates a DNS zone and returns its verification requirements.
Send required name and visibility, with visibility private or public.
A private zone also requires network_id. Public zones return verification and
delegation instructions before publication is enabled.
The response is 201 with zone ID, verification state, and authoritative server
names where applicable. Importing a name does not change registrar delegation.
An already managed zone returns 409 zone_conflict.
Publish a record set
/organizations/{organization_id}/projects/{project_id}/dns-zones/{zone_id}/recordsPublishes a record set within the selected zone.
Accepts name, type, ttl_seconds, and
values. TTL defaults to 300; accepted values are integers 30–86400 inclusive.
The owner name is relative to the zone; @ selects the apex.
To publish an IPv4 address for the api name, send this record set:
{
"name": "api",
"type": "A",
"ttl_seconds": 300,
"values": ["203.0.113.20"]
}A and AAAA values are address literals. CNAME values are target hostnames. MX
and SRV use structured entries with their required numeric fields. TXT values
preserve submitted text. Unsupported types or malformed values return 422
with the value index.
The request returns 202 with record-set ID and publication operation. A CNAME
cannot coexist with other data at the same owner; conflicting records return
409 record_conflict.
Read publication
/organizations/{organization_id}/projects/{project_id}/dns-zones/{zone_id}/records/{record_id}Returns desired values, active publication revision, state, and ETag. Requires networks:read. Zone reads
include verification status and delegation observations.
A successful publication means the authoritative service applied the revision. It does not mean all recursive resolvers have expired their earlier answer. Reducing TTL does not shorten the TTL already cached elsewhere.
Replace and delete
/organizations/{organization_id}/projects/{project_id}/dns-zones/{zone_id}/records/{record_id}Replaces record-set values through a conditional update.
Requires If-Match. values replaces the full RRset;
an empty values array is rejected. Accepted changes return 202.
/organizations/{organization_id}/projects/{project_id}/dns-zones/{zone_id}/records/{record_id}Withdraws the set explicitly. Requires If-Match and returns 202 with a
publication operation, preserving its history.
/organizations/{organization_id}/projects/{project_id}/dns-zones/{zone_id}Deletes the zone and its managed records after dependency checks. Requires the current zone ETag. Registrar delegation and external secondary copies remain under their operators' control.
See DNS, IPv6 publication, and public addresses for planned endpoint changes.
Health-based answer policy
A record-set update can include failover_policy with primary and fallback
targets, approved health-check references, threshold policy, and explicit
no_healthy_target behavior. The field defaults to absent for static answers.
Unknown check references or unsupported record types return 422.
The policy's evaluation and active publication revision remain separate in reads. Changing a policy cannot expire answers already cached by clients. See DNS failover for unknown states and no-healthy-target behavior.
Read zone verification
/organizations/{organization_id}/projects/{project_id}/dns-zones/{zone_id}Returns visibility, ownership verification, delegation observations, publication state, and ETag. Reading does not change registrar delegation.