List DNS zone records
GET /api/v2/dns-zones/{id}/records
Lists the records in a DNS zone with a short summary of the zone. All records come back in one response. There is no paging. GET /api/v2/dns-zones/{id} returns the same. Filter with type and name to see the records already at a name before you add or change one. A create never replaces existing records. Use records[].id to update or delete a record. zone.recordCount counts the records in this response. zone.totalRecordCount, zone.liveRecordLimit and zone.exceedsLiveRecordLimit describe the whole zone.
Authentication: An API key with the scope read:dns. About keys and scopes
Request
Path parameters
idstringrequiredThe DNS zone ID. From
GET /api/v2/dns-zones.Query parameters
typestringReturn only records of this type, for example
MX. SPF policies are TXT records. One of A, AAAA, CNAME, ALIAS, MX, TXT, NS, SRV, CAA, TLSA.namestringReturn only records with this owner name:
@ for the apex, a label such as mail or a full name such as mail.example.com.Example
curl "https://cloud.hostup.se/api/v2/dns-zones/zone_01hxa3b4c5d6e7f8g9h0j1k2m3/records" \ -H "Authorization: Bearer $HOSTUP_API_KEY"Responses
200 The zone summary and its records.
{ "zone": { "id": "zone_01hxa3b4c5d6e7f8g9h0j1k2m3", "name": "example.com", "status": "active", "recordCount": 2, "totalRecordCount": 8, "liveRecordLimit": 200, "exceedsLiveRecordLimit": false }, "records": [ { "id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m3", "type": "A", "name": "example.com", "value": "192.0.2.10", "ttl": 3600 }, { "id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m4", "type": "A", "name": "www.example.com", "value": "192.0.2.10", "ttl": 3600 } ]}{ "zone": { "id": "zone_01hxa3b4c5d6e7f8g9h0j1k2m3", "name": "example.com", "status": "active", "recordCount": 1, "totalRecordCount": 306, "liveRecordLimit": 200, "exceedsLiveRecordLimit": true, "warnings": [ { "code": "dns_live_record_limit_exceeded", "severity": "warning", "message": "This zone has 306 DNS records. Only the first 200 records can be published live; records beyond that limit may be saved but not resolve." } ] }, "records": [ { "id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m5", "type": "TXT", "name": "_dmarc.example.com", "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com", "ttl": 3600 } ]}Response fields
zoneobjectidstringThe DNS zone ID.
namestringThe zone’s domain name.
statusstringZone status. One of
active, disabled, pending, error, unknown.recordCountintegerRecords in this response, after the
type and name filters.totalRecordCountintegerRecords in the whole zone before filters, without SOA and apex NS records.
liveRecordLimitintegerHow many records the zone can publish live.
exceedsLiveRecordLimitbooleanTrue when
totalRecordCount is above liveRecordLimit. Records past the limit may be saved but not resolve.warningsarray of objectZone warnings. Present when
exceedsLiveRecordLimit is true.codestringWarning code. One of
dns_live_record_limit_exceeded.severitystringAlways
warning. One of warning.messagestringThe warning in plain English.
recordsarray of objectThe zone’s records, after filters. Names are full names, such as
_dmarc.example.com. The domain itself is example.com. The list includes the zone’s SOA record and its NS records at the domain itself. totalRecordCount leaves those out.idstringtypestringOne of
A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA, SOA.namestringThe full name, such as
_dmarc.example.com. The domain itself is example.com.valuestringttlintegerpriorityinteger or nullPresent only on MX and SRV records.
null when the DNS server returned no priority.weightinteger or nullPresent only on SRV records.
null when the DNS server returned no weight.portinteger or nullPresent only on SRV records.
null when the DNS server returned no port.proxiedbooleanWhether the record goes through the CDN proxy. Present only on A, AAAA and CNAME records when the proxy state is known.
proxyReasonstringWhy the proxy state of this record cannot be changed, ready to show. Present only when there is such a reason.
actionsobjectAction gates for this record. Present only when one applies.
canChangeProxyobjectallowedbooleanreasonstring or nullcodestring or nullA machine-readable code for why the action is blocked.
warningsarray of objectPresent only on a create response (
POST /api/v2/dns-zones/{id}/records) when the record was added but the records with the same name need a look. Examples: several A records, AAAA records left over, several MX records.codestringOne of
same_name_address_records, same_name_ipv6_records, same_name_mx_records.severitystringOne of
warning.messagestringrecordsarray of objectThe existing records behind the warning. The record you created or changed is the main response.
idstringtypestringnamestringvaluestringpriorityinteger or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is dns_zone_not_found. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |