## POST /api/v2/cdn/zones/{id}

**Prepare or check CDN setup**

Runs one CDN setup step for a zone. Send one `action` and no other fields, except `hostnames` with `prepare_partial`. The domain must be active. Otherwise the call returns `404 cdn_zone_not_found`. Every step returns the full zone, as from `GET /api/v2/cdn/zones/{id}`.

There are two ways to put a domain behind the CDN.

**Move to Hostup's nameservers.** While `actions.canPrepareNameservers` is allowed, Hostup's nameservers do not answer for the zone yet. A nameserver change at that point takes the domain offline. Send `prepare_nameservers` first. It queues the zone on Hostup's nameservers and never changes the domain's nameservers. Publication runs in the background. Read `GET /api/v2/cdn/zones/{id}` every few seconds until `actions.canPrepareNameservers.allowed` is `false`. Then switch the domain to `setup.expectedNameservers`. For a domain registered with Hostup, use `POST /api/v2/domains/{id}/nameservers`. For a domain registered elsewhere, set them at that registrar. Repeating the step is safe. A zone that uses external DNS setup returns `409`.

**Keep your external DNS.** `prepare_partial` prepares the zone and returns an ownership TXT record in `setup.verification` and one CNAME or ALIAS record per hostname in `setup.routing`. To choose the hostnames, send `hostnames`: 1 to 50 names at or below the zone, without wildcards, URL schemes or paths. It changes nothing at your DNS provider. Publish exactly the returned records there. An apex record needs ALIAS or CNAME flattening support at that provider. Then send `check_partial` to recheck verification, routing and the certificate.

HTTP 200 means the step ran, not that the CDN is live. `pending_verification`, `pending_routing` and `pending_certificate` name the work still open. Only `setup.status: active` means traffic and HTTPS run through the CDN. Settings such as proxying and security are changed with `PATCH /api/v2/cdn/zones/{id}`.

### Related Endpoints

- `GET /api/v2/cdn/zones/{id}`: Get a CDN zone
- `PATCH /api/v2/cdn/zones/{id}`: Update CDN zone settings
- `DELETE /api/v2/cdn/zones/{id}`: Turn off the CDN for a zone

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scopes: `write:cdn`, `write:domains`
- `Content-Type`: application/json

### Parameters

- `id` (path, string, required): The CDN zone ID. From `GET /api/v2/cdn/zones`. Example: `cdn_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `action` (string, required): Prepare the setup with your own DNS for the selected zone.
  Allowed values: prepare_partial
- `hostnames` (array<string>, optional): Full hostnames equal to the zone or below it. Leave it out for the apex and `www`. Send 1 to 50 entries. Duplicates are merged. Wildcards, URL schemes and paths are rejected. Case, IDNs and a trailing dot are normalized. The current origins are read from your DNS records. Example: `["example.com","www.example.com"]`

### Request Examples

#### Prepare the default hostnames

```bash
curl -X POST "https://cloud.hostup.se/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "prepare_partial"
  }'
```

```json
{
  "action": "prepare_partial"
}
```

#### Prepare only www

```bash
curl -X POST "https://cloud.hostup.se/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "prepare_partial",
    "hostnames": [
      "www.example.com"
    ]
  }'
```

```json
{
  "action": "prepare_partial",
  "hostnames": [
    "www.example.com"
  ]
}
```

#### Check DNS and certificate readiness

```bash
curl -X POST "https://cloud.hostup.se/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "check_partial"
  }'
```

```json
{
  "action": "check_partial"
}
```

#### Queue the zone for the managed nameservers before a nameserver change

```bash
curl -X POST "https://cloud.hostup.se/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "prepare_nameservers"
  }'
```

```json
{
  "action": "prepare_nameservers"
}
```

### Response Schema

- `setup` (object, optional): How the CDN is set up for the zone: with Hostup's nameservers or with your own DNS. Read `status` and `reason` as returned. A prepared partial setup is not active until the verification, the routing and the HTTPS certificate are confirmed. Copy the DNS names and values as returned. Don't build them yourself.
- `setup.mode` (string, required): `full`: the domain uses Hostup's nameservers. `partial`: your own DNS stays authoritative and chosen hostnames are routed through the CDN. `currentNameservers` shows the nameservers seen now.
  Allowed values: full, partial, unknown
- `setup.status` (string, required): Overall readiness. A `pending_…` status names the next setup step. `unavailable` means the state could not be read. It does not mean that DNS or the certificate is wrong.
  Allowed values: not_configured, pending_verification, pending_routing, pending_certificate, active, unavailable
- `setup.reason` (string, required, nullable): The setup state in words. Null when nothing needs explaining.
- `setup.verification` (object, required, nullable): The TXT record that proves ownership, to publish at your DNS provider. Null when none is needed or available. Copy the name and value exactly.
- `setup.routing` (array<object>, required): The chosen hostnames with the origin values kept when the setup was prepared. Each row has the DNS change it needs at your DNS provider. Publish the routing record without other, conflicting record types at the same name. A row with `status: unsupported` is not set up.
- `setup.routing[].hostname` (string, required) Example: `www.example.com`
- `setup.routing[].currentOrigin` (array<object>, required)
- `setup.routing[].currentOrigin[].type` (string, required)
  Allowed values: A, AAAA, CNAME
- `setup.routing[].currentOrigin[].value` (string, required) Example: `203.0.113.10`
- `setup.routing[].record` (object, required, nullable): The exact routing record to publish at your DNS provider. Null when none is available. Use `ALIAS` only when your provider supports a flattened alias at the zone apex. Don't replace an apex with a plain CNAME when that conflicts with the other records at the apex.
- `setup.routing[].status` (string, required)
  Allowed values: pending, verified, unsupported, unknown
- `setup.routing[].reason` (string, required, nullable)
- `setup.certificate` (object, required)
- `setup.certificate.status` (string, required)
  Allowed values: active, pending, error, unknown
- `setup.certificate.hosts` (array<string>, required): Hostnames on the CDN's HTTPS certificate.
- `setup.checkedAt` (string, required, nullable): When the setup was last checked, in UTC. Null when unknown.
- `setup.currentNameservers` (array<string>, required)
- `setup.expectedNameservers` (array<string>, required): Hostup's nameservers, for a full setup. A partial setup does not need them. Example: `["primary.ns.hostup.se","secondary.ns.hostup.se"]`
- `setup.registrarRelation` (string, required): Where the registration of the domain is managed. It does not depend on the CDN setup mode.
  Allowed values: hostup, external, unknown
- `setup.nameserverManagementUrl` (string, required, nullable): Link to change the nameservers in the client area, when the domain is registered with Hostup. Otherwise null. To use Hostup's nameservers then, set `expectedNameservers` at your registrar.
- `id` (string, optional, nullable): The CDN zone ID (`cdn_…`). Set even before the CDN is set up. Null only when the zone cannot be identified. Example: `cdn_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `domain` (string, optional) Example: `example.com`
- `domainId` (string, optional, nullable): The domain ID (`dom_…`) for a domain registered with Hostup. `null` for a DNS-only zone. Example: `dom_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `status` (string, optional) Example: `active`
  Allowed values: active, pending, misconfigured, missing, disabled
- `reason` (string, optional, nullable) Example: `null`
- `proxied` (boolean, optional) Example: `true`
- `securityLevel` (string, optional) Example: `medium`
  Allowed values: off, low, medium, high
- `ssl` (object, optional)
- `ssl.status` (string, required) Example: `active`
  Allowed values: active, pending, error
- `ssl.expiresAt` (string, required, nullable) Example: `2026-08-01T00:00:00.000Z`
- `ruleCount` (integer, optional) Example: `2`
- `security` (object, optional)
- `security.level` (string, required): Overall CDN security level. Example: `medium`
  Allowed values: off, low, medium, high
- `security.sslMode` (string, required): The TLS mode between visitors, the CDN and your origin server. Example: `full`
  Allowed values: off, flexible, full, strict
- `security.alwaysUseHttps` (boolean, required) Example: `true`
- `security.minTlsVersion` (string, required) Example: `1.2`
  Allowed values: 1.0, 1.1, 1.2, 1.3
- `security.botProtection` (boolean, required) Example: `true`
- `security.blockBadCrawlers` (boolean, required) Example: `true`
- `security.blockBadBots` (boolean, required) Example: `true`
- `security.wpLoginProtection` (boolean, required): Protect the WordPress login pages. Example: `true`
- `security.wpAdminChallenge` (boolean, required): Challenge requests to the WordPress admin paths. Example: `true`
- `security.blockedCrawlers` (array<string>, required): Crawler catalogue IDs that are blocked before every other rule, verified-bot exemptions included. Examples: `baiduspider`, `gptbot`, `claudebot`, `ahrefsbot`. Lowercase IDs only. The crawler catalogue has the full list. Empty unless crawlers were chosen. Separate from `blockBadCrawlers`, the general check for bad crawlers. Example: `["baiduspider","gptbot"]`
- `performance` (object, optional)
- `performance.earlyHints` (boolean, required) Example: `true`
- `performance.alwaysOnline` (boolean, required) Example: `true`
- `cache` (object, optional)
- `cache.purgeCache` (boolean, required): The saved cache-purge setting. Example: `false`
- `waf` (object, optional)
- `waf.skipEnabled` (boolean, required): Whether your own WAF skip rules are on. Example: `false`
- `waf.challengeGeoEnabled` (boolean, required): Whether the country challenge of the visitor profile is on. Example: `true`
- `waf.visitorProfileMode` (string, required): `challenge`: visitors from outside the allowed countries must pass a challenge. `block`: they are blocked. `off`: the visitor profile does nothing. Example: `challenge`
  Allowed values: off, challenge, block
- `waf.ipAllowlist` (array<string>, required): IP addresses or CIDR ranges that skip the custom WAF checks. Example: `["203.0.113.10"]`
- `waf.uaAllowlist` (array<string>, required): User-agent substrings that skip the custom WAF checks. Example: `["HostUp-Monitor"]`
- `waf.pathAllowlist` (array<string>, required): Path prefixes that skip the custom WAF checks. Example: `["/health"]`
- `waf.uaBlocklist` (array<string>, required): User-agent substrings that are blocked before every allowlist and verified-bot exemption. Entries equal to or contained in ordinary browser tokens, such as `Mozilla`, `Chrome` or `bot`, are rejected with `invalid_request`. They would block ordinary visitors. Example: `["MegaIndex"]`
- `waf.ipBlocklist` (array<string>, required): IPv4 or IPv6 addresses or CIDR ranges that are blocked before every allowlist and verified-bot exemption. Example: `["198.51.100.0/24"]`
- `geoRestriction` (object, optional)
- `geoRestriction.enabled` (boolean, required) Example: `true`
- `geoRestriction.whitelistCountries` (array<string>, required): Older field with the allowed country codes, in capitals. Use `combinedCountries` instead. Example: `["SE"]`
- `geoRestriction.mode` (string, required): `off`: no country limit. `whitelist`: only the countries in `combinedCountries` are allowed. Example: `whitelist`
  Allowed values: off, whitelist
- `geoRestriction.standardCountries` (array<string>, required): Countries that are always allowed. You cannot remove them. Example: `[]`
- `geoRestriction.additionalCountries` (array<string>, required): Country codes you added on top of `standardCountries`. Example: `["SE"]`
- `geoRestriction.combinedCountries` (array<string>, required): The allowed countries: `standardCountries` plus `additionalCountries`. Example: `["SE"]`
- `activity` (object, optional)
- `activity.lastChangeDetectedAt` (string, required, nullable) Example: `2026-04-27T12:00:00.000Z`
- `activity.lastCheckedAt` (string, required, nullable) Example: `2026-04-27T12:00:00.000Z`
- `activity.settingsUpdatedAt` (string, required, nullable) Example: `2026-04-27T12:00:00.000Z`
- `actions` (object, optional)
- `actions.canEnableProxy` (object, required)
- `actions.canEnableProxy.allowed` (boolean, required) Example: `true`
- `actions.canEnableProxy.reason` (string, required, nullable) Example: `null`
- `actions.canEnableProxy.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canIssueCertificate` (object, required)
- `actions.canIssueCertificate.allowed` (boolean, required) Example: `true`
- `actions.canIssueCertificate.reason` (string, required, nullable) Example: `null`
- `actions.canIssueCertificate.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canChangeMode` (object, required)
- `actions.canChangeMode.allowed` (boolean, required) Example: `true`
- `actions.canChangeMode.reason` (string, required, nullable) Example: `null`
- `actions.canChangeMode.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canActivate` (object, required)
- `actions.canActivate.allowed` (boolean, required) Example: `true`
- `actions.canActivate.reason` (string, required, nullable) Example: `null`
- `actions.canActivate.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canDeactivate` (object, required)
- `actions.canDeactivate.allowed` (boolean, required) Example: `true`
- `actions.canDeactivate.reason` (string, required, nullable) Example: `null`
- `actions.canDeactivate.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canPreparePartial` (object, required): Whether you can prepare a setup with your own DNS. The request also checks the current delegation. A full setup that is delegated now cannot be converted with this action.
- `actions.canPreparePartial.allowed` (boolean, required) Example: `true`
- `actions.canPreparePartial.reason` (string, required, nullable) Example: `null`
- `actions.canPreparePartial.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canCheckPartial` (object, required): Whether an existing partial setup can be checked now.
- `actions.canCheckPartial.allowed` (boolean, required) Example: `true`
- `actions.canCheckPartial.reason` (string, required, nullable) Example: `null`
- `actions.canCheckPartial.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `actions.canPrepareNameservers` (object, required): Whether the zone still has to be published on Hostup's nameservers before you switch the domain to them. Allowed while it is not published there. Then send `prepare_nameservers` to `POST /api/v2/cdn/zones/{id}`. Read the zone until this gate closes. Only then change the nameservers. Not allowed when the zone is already published, when it uses your own DNS or when readiness was not checked.
- `actions.canPrepareNameservers.allowed` (boolean, required) Example: `true`
- `actions.canPrepareNameservers.reason` (string, required, nullable) Example: `null`
- `actions.canPrepareNameservers.code` (string, optional, nullable): A machine-readable code for why the action is blocked. Example: `pending_order`
- `records` (array<any>, optional, nullable): `null` unless you send `includeRecords=true`.

### Responses

#### 200 - The zone after the step. A pending setup state or an open `canPrepareNameservers` gate is a normal result.
```json
{
  "id": "cdn_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "domain": "example.com",
  "domainId": "dom_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "status": "pending",
  "reason": "Add the verification TXT record at your DNS provider.",
  "proxied": false,
  "securityLevel": "medium",
  "ssl": {
    "status": "pending",
    "expiresAt": null
  },
  "ruleCount": 2,
  "security": {
    "level": "medium",
    "sslMode": "full",
    "alwaysUseHttps": true,
    "minTlsVersion": "1.2",
    "botProtection": true,
    "blockBadCrawlers": true,
    "blockBadBots": true,
    "wpLoginProtection": true,
    "wpAdminChallenge": true,
    "blockedCrawlers": []
  },
  "performance": {
    "earlyHints": true,
    "alwaysOnline": true
  },
  "cache": {
    "purgeCache": false
  },
  "waf": {
    "skipEnabled": false,
    "challengeGeoEnabled": true,
    "visitorProfileMode": "challenge",
    "ipAllowlist": [
      "198.51.100.10"
    ],
    "uaAllowlist": [
      "ExampleMonitor/1.0"
    ],
    "pathAllowlist": [
      "/health"
    ],
    "uaBlocklist": [],
    "ipBlocklist": []
  },
  "geoRestriction": {
    "enabled": true,
    "whitelistCountries": [
      "SE"
    ],
    "mode": "whitelist",
    "standardCountries": [],
    "additionalCountries": [
      "SE"
    ],
    "combinedCountries": [
      "SE"
    ]
  },
  "activity": {
    "lastChangeDetectedAt": "2026-04-27T12:00:00.000Z",
    "lastCheckedAt": "2026-04-27T12:00:00.000Z",
    "settingsUpdatedAt": "2026-04-27T12:00:00.000Z"
  },
  "actions": {
    "canEnableProxy": {
      "allowed": false,
      "reason": "Add the verification TXT record at your DNS provider."
    },
    "canIssueCertificate": {
      "allowed": true,
      "reason": null
    },
    "canChangeMode": {
      "allowed": true,
      "reason": null
    },
    "canActivate": {
      "allowed": false,
      "reason": "Add the verification TXT record at your DNS provider."
    },
    "canDeactivate": {
      "allowed": false,
      "reason": "CDN is not active for this domain."
    },
    "canPreparePartial": {
      "allowed": false,
      "reason": "External DNS setup is already prepared. Check its current status."
    },
    "canCheckPartial": {
      "allowed": true,
      "reason": null
    },
    "canPrepareNameservers": {
      "allowed": false,
      "reason": "External DNS setup is prepared for this domain."
    }
  },
  "records": null,
  "setup": {
    "mode": "partial",
    "status": "pending_verification",
    "reason": "Add the verification TXT record at your DNS provider.",
    "verification": {
      "type": "TXT",
      "name": "cdn-verification.example.com",
      "value": "example-verification-value",
      "status": "pending"
    },
    "routing": [
      {
        "hostname": "www.example.com",
        "currentOrigin": [
          {
            "type": "A",
            "value": "198.51.100.10"
          }
        ],
        "record": {
          "type": "CNAME",
          "name": "www.example.com",
          "value": "www.example.com.cdn.example.net"
        },
        "status": "pending",
        "reason": null
      }
    ],
    "certificate": {
      "status": "pending",
      "hosts": []
    },
    "checkedAt": "2026-04-27T12:00:00.000Z",
    "currentNameservers": [
      "ns1.example.net",
      "ns2.example.net"
    ],
    "expectedNameservers": [
      "primary.ns.hostup.se",
      "secondary.ns.hostup.se"
    ],
    "registrarRelation": "hostup",
    "nameserverManagementUrl": "/domains/example.com?tab=nameservers"
  }
}
```

#### 400 - The action is missing or unknown, `hostnames` is invalid or the body has other fields.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Validation failed",
  "status": 400,
  "detail": "Choose prepare_partial, check_partial or prepare_nameservers. prepare_partial optionally accepts 1–50 hostnames within this domain; no other fields are accepted.",
  "code": "invalid_request",
  "instance": "/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - Forbidden. The caller lacks a required scope or does not own the resource.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The caller lacks a required scope or does not own the resource.",
  "code": "forbidden",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 404 - No CDN zone with this ID on the account. The domain may also not be active.
```json
{
  "type": "https://developer.hostup.se/errors/cdn_zone_not_found",
  "title": "CDN zone not found",
  "status": 404,
  "detail": "The requested CDN zone could not be found.",
  "code": "cdn_zone_not_found",
  "instance": "/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
```

#### 409 - `prepare_nameservers` does not apply. Either the zone uses external DNS setup or another account holds the domain's DNS zone.
```json
{
  "type": "https://developer.hostup.se/errors/domain_conflict",
  "title": "External DNS setup is in use",
  "status": 409,
  "detail": "External DNS setup is prepared for this domain, so there are no Hostup nameservers to prepare.",
  "code": "domain_conflict",
  "instance": "/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 502 - The setup step returned no usable result. Read the zone before you retry.
```json
{
  "type": "https://developer.hostup.se/errors/upstream_failed",
  "title": "CDN setup status unavailable",
  "status": 502,
  "detail": "External DNS setup could not be completed. Refresh its status before retrying.",
  "code": "upstream_failed",
  "instance": "/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
```

#### 503 - The setup step cannot run right now. Try again later.
```json
{
  "type": "https://developer.hostup.se/errors/service_unavailable",
  "title": "Nameserver preparation unavailable",
  "status": 503,
  "detail": "The DNS zone could not be queued for Hostup's nameservers right now. Try again shortly.",
  "code": "service_unavailable",
  "instance": "/api/v2/cdn/zones/cdn_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
```
