## POST /api/v2/shared-hosting/{accountId}/domains/dns-setup

**Apply the DNS setup of a hosting domain**

Points the website, the email or both of a domain at the web hosting account. It can also save that the current DNS stays. `full` moves website and email. `website-only` and `email-only` move one and leave the other. `none` changes no records. It saves the choice and stops the hosting account from changing the website and mail records later. Read `GET /api/v2/shared-hosting/{accountId}/domains/dns-setup` first and send its `revision` with every choice except `none`. A `revision` that no longer matches returns 409 `dns_changed`. A choice that includes email also publishes the account's DKIM key and sets the domain to receive its mail on the hosting account. The choice can be saved while the domain uses other nameservers. It takes effect when they move to Hostup. `status: pending` means the new records are not all visible yet. Read the setup again until `publication` is no longer `pending`. Only the first read that finds the records in place says `done`. Later reads say `null`.

### Related Endpoints

- `GET /api/v2/shared-hosting/{accountId}/domains/dns-setup`: Get the DNS setup of a hosting domain
- `GET /api/v2/shared-hosting/{accountId}/domains`: List hosting domains
- `POST /api/v2/shared-hosting/{accountId}/domains`: Add a domain to web hosting

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scopes: `write:hosting`, `write:dns`, `console:services`
- `Content-Type`: application/json

### Parameters

- `accountId` (path, string, required): The hosting account ID (`acct_…`). Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `domain` (string, required): Main domain, addon domain or parked domain of the hosting account. Example: `example.com`
- `preference` (string, required): `full`: website and email to the hosting account. `website-only`: only the website. `email-only`: only email. `none`: keep the current DNS. The hosting account then leaves the website and mail records alone. Example: `full`
  Allowed values: full, email-only, website-only, none
- `revision` (string, optional): The `revision` from the latest GET. Needed for every choice except `none`. A missing or old value returns 409 `dns_changed`. Example: `5f8c1d2e9a7b4c3d6e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d`

### Request Examples

#### Website and email to the hosting

```bash
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "preference": "full",
    "revision": "5f8c1d2e9a7b4c3d6e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d"
  }'
```

```json
{
  "domain": "example.com",
  "preference": "full",
  "revision": "5f8c1d2e9a7b4c3d6e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d"
}
```

#### Keep the current DNS and save the choice

```bash
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "preference": "none"
  }'
```

```json
{
  "domain": "example.com",
  "preference": "none"
}
```

### Response Schema

- `success` (boolean, required): Always `true`. Example: `true`
  Allowed values: true
- `domain` (string, required): The domain. Example: `example.com`
- `preference` (string, required): The saved choice. Example: `full`
  Allowed values: full, email-only, website-only, none
- `status` (string, required): `done` when the records already match the setup. `pending` while they are still being published. Example: `done`
  Allowed values: done, pending

### Responses

#### 200 - The choice is saved. Records are written for every choice except `none`.
```json
{
  "success": true,
  "domain": "example.com",
  "preference": "full",
  "status": "done"
}
```

#### 400 - `domain` or `preference` is missing or invalid.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "DNS setup",
  "status": 400,
  "detail": "A domain and a valid DNS setup choice are required.",
  "code": "invalid_request",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup"
}
```

#### 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 - The API key lacks a required scope or the hosting account is not active.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to access this resource.",
  "code": "forbidden",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller.
```json
{
  "type": "https://developer.hostup.se/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 409 - The change is blocked and nothing was written. `code` says why: `dns_changed` (the records changed since the GET), `dns_forwarding_active` (domain email forwarding is on; turn it off before you move email), `dns_redirect_active` (a domain redirect uses the website records; remove it before you move the website), `dns_plan_conflict` (the records need review in the DNS editor), `dns_mirror_pending` (the hosting DNS view is still updating; try again shortly), `dns_mail_key_unavailable` (the account's mail key is not ready yet), `dns_busy` (another DNS change is running) or `dns_not_enabled` (the account does not offer this setup).
```json
{
  "type": "https://developer.hostup.se/errors/dns_changed",
  "title": "DNS setup",
  "status": 409,
  "detail": "The DNS settings changed. Review the refreshed settings before saving.",
  "code": "dns_changed",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup"
}
```

#### 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 change failed on the server. `code` is `domain_not_attached` when the domain is not the main, an addon or a parked domain of the account; nothing was written and a retry does not help. Otherwise `code` is `dns_read_unavailable` and some records may already be written. Read the setup again before you retry.
```json
{
  "type": "https://developer.hostup.se/errors/domain_not_attached",
  "title": "DNS setup",
  "status": 502,
  "detail": "The domain is no longer attached to this hosting account.",
  "code": "domain_not_attached",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup"
}
```

#### 503 - The setup cannot run now. Nothing was changed. This happens when the GET shows `canApply: false` or `revision: null`: the DNS zone or the nameservers could not be read, the domain has no DNS zone at Hostup, or the hosting address is not known. Read the setup again and send the choice once `canApply` is `true` and `revision` is set.
```json
{
  "type": "https://developer.hostup.se/errors/dns_read_unavailable",
  "title": "DNS setup",
  "status": 503,
  "detail": "The DNS settings could not be checked. Please try again.",
  "code": "dns_read_unavailable",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup"
}
```
