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
idstringrequiredGET /api/v2/dns-zones.recordIdstringrequiredGET /api/v2/dns-zones/{id}.Body
typestringA, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA.namestring@ 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.valuestringttlintegerpriorityintegerweightintegerportintegerproxiedbooleantrue 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
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 }'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": "@", "value": "192.0.2.1", "ttl": 3600 }'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": "AAAA", "name": "@", "value": "2001:db8::1", "ttl": 3600 }'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": "CNAME", "name": "www", "value": "target.example.com", "ttl": 3600 }'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": "ALIAS", "name": "@", "value": "target.example.com", "ttl": 3600 }'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": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=quarantine", "ttl": 3600 }'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": "MX", "name": "@", "value": "mail.example.com", "priority": 10, "ttl": 3600 }'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": "SRV", "name": "_sip._tcp", "value": "sip.example.com", "priority": 10, "weight": 5, "port": 5060, "ttl": 3600 }'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": "CAA", "name": "@", "value": "0 issue \"letsencrypt.org\"", "ttl": 3600 }'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": "TLSA", "name": "_443._tcp", "value": "3 1 1 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "ttl": 3600 }'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": "NS", "name": "acme", "value": "ns1.acme.example.net", "ttl": 3600 }'Responses
200 The updated record. An update response has no warnings. Only the create endpoint adds them.
{ "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
idstringtypestringA, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA, SOA.namestring_dmarc.example.com. The domain itself is example.com.valuestringttlintegerpriorityinteger or nullnull when the DNS server returned no priority.weightinteger or nullnull when the DNS server returned no weight.portinteger or nullnull when the DNS server returned no port.proxiedbooleanproxyReasonstringactionsobjectcanChangeProxyobjectallowedbooleanreasonstring or nullcodestring or nullwarningsarray of objectPOST /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.codestringsame_name_address_records, same_name_ipv6_records, same_name_mx_records.severitystringwarning.messagestringrecordsarray of objectidstringtypestringnamestringvaluestringpriorityinteger 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: 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. |
| 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 names the missing resource: dns_zone_not_found, dns_record_not_found. |
| 409 | The 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. |
| 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. |
| 503 | The 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. |