Skip to content

Set CDN proxying for a DNS record

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

Turns CDN proxying on or off for one A, AAAA or CNAME record. The body is { "proxied": true } or { "proxied": false } and nothing else. Use PUT /api/v2/dns-zones/{id}/records/{recordId} to change the record itself. The CDN proxy rule behind the record is created or updated for you.

Turning proxying on needs an active CDN on the zone. Some records cannot change their proxy state, for example mail and webmail names, nested subdomains and records an MX record points to. A refused change returns 409 dns_record_proxy_blocked. To check first, read the record from GET /api/v2/domains/{id}/dns. It takes the domain ID, not the zone ID, and needs read:domains and read:cdn besides read:dns. Each A, AAAA and CNAME record there carries proxied and actions.canChangeProxy. Without read:cdn those fields are left out.

Authentication: An API key with the scopes write:cdn and read:dns. 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

proxiedboolean
True sends the record through the CDN proxy. False makes it DNS only. Valid only for A, AAAA and CNAME records.

Example

PATCH /api/v2/dns-zones/{id}/records/{recordId}
curl -X PATCH "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 '{
"proxied": true
}'

Responses

200 The record with its new proxy state.

Response 200
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m4",
"type": "A",
"name": "www.example.com",
"value": "192.0.2.10",
"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. 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: dns_zone_not_found, dns_record_not_found.
409This record cannot change its proxy state. detail says why.
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 CDN proxy rule could not be read or changed right now. code is external_provider_failed. Nothing was changed. Some of these failures come with status 500 and the same code. Retry later.