Skip to content

Update a DNS record

PUT /api/v2/dns-zones/{id}/records/{recordId}

Replaces one DNS record with the record in the body. Use this PUT route, not PATCH, to change type, name, value, ttl or priority. Send the whole record, not only the fields that change. type and value are required. A missing name means the zone root and a missing ttl means 3600, so send the current name and ttl to keep them. The record is validated as in POST /api/v2/dns-zones/{id}/records. As there, a missing or invalid field returns 400 that names the field in errors[].pointer. A record the DNS service refuses returns 400 with a general detail. The record being edited does not count as a duplicate of itself. When another record already has the new type, name and value, the edited record is deleted and the response is that other record, with its own ID. A change that would put a CNAME and other records on the same name returns 409 dns_conflict. Use ALIAS, not CNAME, to point the apex at another hostname. SPF policies are TXT records whose value starts with v=spf1. An NS record delegates a subdomain only.

Add proxied on an A, AAAA or CNAME record to turn CDN proxying on or off in the same request. With any other type, sending proxied, even false, returns 409 dns_record_proxy_blocked. Turning it on needs an active CDN on the zone. A refused proxy change returns 409 dns_record_proxy_blocked and leaves the record unchanged. Without proxied, a proxied record stays proxied when the new record allows it. Otherwise its proxy rule is removed. A key without write:cdn cannot carry proxying over to a new name or type. Moving an A or AAAA record off a Hostup web-hosting address also switches CDN proxying off for the name. Without write:cdn that move still changes the record, then returns 401 external_provider_failed. Use a key with write:cdn for such a change.

Authentication: An API key with the scope write:dns. Also write:cdn: only when the body sets proxied. About keys and scopes

Request

Path parameters

idstringrequired
The DNS zone ID. From GET /api/v2/dns-zones.
recordIdstringrequired
The DNS record ID. From GET /api/v2/dns-zones/{id}.

Body

typestring
One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA.
namestring
The record name relative to this DNS zone: @ or an empty string for the zone root, a label such as www or _dmarc below it. Not the full name www.example.com. Always send it. A body without name moves the record to the zone root. Responses return the full name.
valuestring
The target or content of the record. Send TXT values, SPF, DKIM and DMARC included, without surrounding quotes. The server adds the quotes. It splits long TXT values into DNS strings of at most 255 characters.
ttlinteger
Time to live in seconds, from 60 to 86400. Default 3600. Leaving it out sets the record’s TTL to 3600, whatever it was before. Send a JSON number. 60 to 86400.
priorityinteger
Priority, from 0 to 65535. Required for MX and SRV records. Other types refuse it with 400. Send a JSON number. 0 to 65535.
weightinteger
SRV weight, from 0 to 65535. Required for SRV records. Other types refuse it with 400. 0 to 65535.
portinteger
SRV port, from 1 to 65535. Required for SRV records. Other types refuse it with 400. 1 to 65535.
proxiedboolean
CDN proxy setting for an A, AAAA or CNAME record. Leave it out to change only the DNS content. Send true or false to change the proxy setting as well. Send it only for those three types. On any other type, even false returns 409 dns_record_proxy_blocked.

Example

PUT /api/v2/dns-zones/{id}/records/{recordId}
curl -X PUT "https://cloud.hostup.se/api/v2/dns-zones/zone_01hxa3b4c5d6e7f8g9h0j1k2m3/records/drr_01hxa3b4c5d6e7f8g9h0j1k2m3" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "A",
"name": "www",
"value": "192.0.2.1",
"ttl": 3600,
"proxied": true
}'

Responses

200 The updated record. An update response has no warnings. Only the create endpoint adds them.

Response 200
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m3",
"type": "A",
"name": "www.example.com",
"value": "192.0.2.1",
"ttl": 3600,
"proxied": true,
"actions": {
"canChangeProxy": {
"allowed": true,
"reason": null
}
}
}
Response fields
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

Errors

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

400Invalid request. The response body is an RFC 7807 Problem Details document.
401unauthorized: the request has no valid authentication. external_provider_failed: an A or AAAA record moved off a Hostup web-hosting address with a key that lacks write:cdn. The record was changed, but CDN proxying was not switched off. Read the record before you retry.
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: dns_zone_not_found, dns_record_not_found.
409The record was not changed. code says why: dns_conflict when a CNAME would share its name with other records, dns_record_proxy_blocked when the proxy change is refused. detail gives the reason.
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.
503The change could not be completed right now. Retry shortly. upstream_failed: the MX target could not be looked up, and the record is unchanged. external_provider_failed: the DNS record was saved, but its CDN proxy rule could not be changed. Read the record before you retry. external_provider_failed can also come with status 500.