Skip to content

List a domain's DNS records

GET /api/v2/domains/{id}/dns

List the DNS records of a domain. records[] holds the records you can edit. The managed backing records for redirects, parking and email forwarding are left out. parking.active says whether the parking page is on. Filter with type (for example type=MX or type=ALIAS) or name (for example name=mail). SOA and apex NS records are hidden unless includeSystem=true. zone.recordCount counts the records in this response. zone.totalRecordCount counts the whole zone, hidden records included. zone.exceedsLiveRecordLimit is true when the zone has more records than can be published. actions.canManageRootMxRecords.allowed is false while email forwarding handles mail for the domain. With read:cdn, each A, AAAA and CNAME record also has proxied and actions.canChangeProxy. When an active domain uses Hostup’s nameservers but has no DNS zone yet, a key with write:dns creates the zone during this call. A key without it gets zone: null. To change records, use zone.id with GET /api/v2/dns-zones/{id} and the record endpoints next to it. A key limited to certain DNS zones gets 403 for other domains.

Authentication: An API key with the scopes read:dns and read:domains. About keys and scopes

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Query parameters

includeSystemboolean
Include the SOA record (type: SOA) and the NS records at the zone root. Default false. Default false.
typestring
Only records of this type. SPF policies are TXT records. One of A, AAAA, CNAME, ALIAS, MX, TXT, NS, SRV, CAA, TLSA.
namestring
Only records with this name. Use @ for the zone root, a label such as mail or a full name such as mail.example.com.

Example

GET /api/v2/domains/{id}/dns
curl "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/dns" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The domain’s DNS records and zone state.

Response 200
{
"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_01hxa3b4c5d6e7f8g9h0j1k2m4",
"type": "A",
"name": "www.example.com",
"value": "192.0.2.10",
"ttl": 3600,
"proxied": false,
"actions": {
"canChangeProxy": {
"allowed": true,
"reason": null
}
}
}
],
"nameservers": [
"primary.ns.hostup.se",
"secondary.ns.hostup.se"
],
"parking": {
"active": true
},
"actions": {
"canManageRecords": {
"allowed": true,
"reason": null
},
"canManageRootMxRecords": {
"allowed": false,
"reason": "Email forwarding is enabled. Disable email forwarding before adding custom root MX records."
}
}
}
Response fields
zoneobject | null
The domain’s DNS zone at Hostup. null when the domain has no zone there: it uses other nameservers, or the zone has not been created yet. records is then empty.
idstring
The DNS zone ID. Use it with the DNS zone endpoints.
namestring
The zone name.
asciiNamestring
The zone name in ASCII (punycode). Present only for internationalised domain names.
statusstring
The zone’s status. One of active, disabled, pending, error, unknown.
recordCountinteger
Records in records[], after filters.
totalRecordCountinteger
Records in the whole zone, before filters, without the SOA record and the NS records at the zone root. It also counts the hidden parking, redirect and email forwarding records, so it can be higher than recordCount without filters.
liveRecordLimitinteger
The most records the zone can publish at once.
exceedsLiveRecordLimitboolean
True when totalRecordCount is above liveRecordLimit. Records past the limit may be saved but not resolve.
warningsarray of object
Zone warnings. Present when exceedsLiveRecordLimit is true.
codestring
One of dns_live_record_limit_exceeded.
severitystring
One of warning.
messagestring
recordsarray of object
idstring
typestring
One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA, SOA.
namestring
The full name, such as _dmarc.example.com. The domain itself is example.com.
valuestring
ttlinteger
priorityinteger or null
Present only on MX and SRV records. null when the DNS server returned no priority.
weightinteger or null
Present only on SRV records. null when the DNS server returned no weight.
portinteger or null
Present only on SRV records. null when the DNS server returned no port.
proxiedboolean
Whether the record goes through the CDN proxy. Present only on A, AAAA and CNAME records when the proxy state is known.
proxyReasonstring
Why the proxy state of this record cannot be changed, ready to show. Present only when there is such a reason.
actionsobject
Action gates for this record. Present only when one applies.
canChangeProxyobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
warningsarray of object
Present 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.
codestring
One of same_name_address_records, same_name_ipv6_records, same_name_mx_records.
severitystring
One of warning.
messagestring
recordsarray of object
The existing records behind the warning. The record you created or changed is the main response.
idstring
typestring
namestring
valuestring
priorityinteger or null
nameserversarray of string
The domain’s nameservers.
parkingobject
The parking page at the zone root. Its A record is not in records[].
activeboolean
True when the domain shows the parking page.
actionsobject
canManageRecordsobject
Whether your key may add, change or delete records.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canManageRootMxRecordsobject
allowed is false while email forwarding handles mail for the domain. Turn off email forwarding before you add your own MX records at the zone root.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400type is not one of the listed record types. errors[0].code is invalid_record_type.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code names the missing resource: domain_not_found, domain_dns_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.