Skip to content

Create a CDN proxy rule

POST /api/v2/cdn/zones/{id}/proxy-rules

Creates a proxy rule for one hostname in the zone. name is @ for the apex, a label such as www or a full hostname in the zone. mode: "off" creates the rule with proxying off. always and smart both turn proxying on. So does a body without mode. priority defaults to 100. The domain must be active.

A new rule returns 201. When the hostname already has a rule, no second rule is created. The existing rule gets the sent mode, priority and description, is made active and comes back with 200 and unchanged: true. recordType is checked (A, AAAA or CNAME) but does not change the rule. Unknown fields return 400.

To proxy a single DNS record, PATCH /api/v2/dns-zones/{id}/records/{recordId} with proxied is usually simpler. It creates and updates the rule for you.

Authentication: An API key with the scopes write:cdn and write:domains. About keys and scopes

Request

Path parameters

idstringrequired
The CDN zone ID. From GET /api/v2/cdn/zones.

Body

recordTypestring
The DNS record type the rule proxies. One of A, AAAA, CNAME.
namestring
The hostname: a label, @, a full hostname or a subdomain in the zone.
modestring
always proxies the traffic. off creates the rule turned off. smart is reserved. One of always, smart, off.
priorityinteger
0 to 65535.
descriptionstring or null

Example

POST /api/v2/cdn/zones/{id}/proxy-rules
curl -X POST "https://cloud.hostup.se/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3/proxy-rules" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "www",
"mode": "always",
"priority": 100,
"description": "Proxy website traffic through the CDN."
}'

Responses

200 The hostname already had a rule. It was updated with the sent values and is returned with unchanged: true.

Response 200
{
"id": "cprule_01hxa3b4c5d6e7f8g9h0j1k2m3",
"fqdn": "www.example.com",
"zone": "example.com",
"proxy": {
"enabled": true,
"mode": "always",
"priority": 100
},
"state": {
"active": true,
"reason": null
},
"createdAt": "2026-04-27T12:00:00.000Z",
"updatedAt": "2026-04-27T12:00:00.000Z",
"description": "Proxy website traffic through the CDN.",
"unchanged": true
}
Response fields
idstring
The proxy rule ID (cprule_…).
fqdnstring or null
zonestring or null
proxyobject
enabledboolean
modestring
One of always, smart, off.
priorityinteger
0 to 65535.
stateobject
activeboolean
reasonstring or null
createdAtstring or null
updatedAtstring or null
descriptionstring or null
unchangedboolean
Present and true only when POST found a rule for the same hostname and returned it instead of creating a second one.

201 The new rule.

Response 201
{
"id": "cprule_01hxa3b4c5d6e7f8g9h0j1k2m3",
"fqdn": "www.example.com",
"zone": "example.com",
"proxy": {
"enabled": true,
"mode": "always",
"priority": 100
},
"state": {
"active": true,
"reason": null
},
"createdAt": "2026-04-27T12:00:00.000Z",
"updatedAt": "2026-04-27T12:00:00.000Z",
"description": "Proxy website traffic through the CDN."
}
Response fields
idstring
The proxy rule ID (cprule_…).
fqdnstring or null
zonestring or null
proxyobject
enabledboolean
modestring
One of always, smart, off.
priorityinteger
0 to 65535.
stateobject
activeboolean
reasonstring or null
createdAtstring or null
updatedAtstring or null
descriptionstring or null
unchangedboolean
Present and true only when POST found a rule for the same hostname and returned it instead of creating a second one.

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 is cdn_zone_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.