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

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

Shows where the website and email of a domain on the web hosting account point today. It also shows whether its DNS can be pointed at the account. Read it before `POST /api/v2/shared-hosting/{accountId}/domains/dns-setup` and send its `revision` back with the choice. `classification.recommendedPreference` is the choice that keeps the current services working. The domain must be the main domain, an addon domain or a parked domain of the account. The account must be active. A domain that is not on the account returns 503 `domain_not_attached`. Retrying does not help then.

### Related Endpoints

- `POST /api/v2/shared-hosting/{accountId}/domains/dns-setup`: Apply 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: `read:hosting`, `read:dns`, `console:services`

### Parameters

- `accountId` (path, string, required): The hosting account ID (`acct_…`). Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `domain` (query, string, required): Domain on the hosting account, without protocol or path. Example: `example.com`

### Request Example

```bash
curl "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup?domain=example.com" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"
```

### Response Schema

- `domain` (string, required): The domain checked. Example: `example.com`
- `hostingName` (string, required): The hosting account's main domain. Example: `example.se`
- `currentMailAddresses` (array<string>, optional): IP addresses of the domain's current MX hosts, when those hosts are names in this zone. Missing when `enabled` is `false`. Example: `[]`
- `enabled` (boolean, required): `false` when this hosting account does not offer the setup. `POST` then returns 409 `dns_not_enabled`. Example: `true`
- `delegation` (string, required): `hostup`: the domain uses Hostup's nameservers. `external`: other nameservers. `unknown`: the lookup failed. A choice can be saved while the delegation is `external`. It takes effect when the nameservers move to Hostup. Example: `hostup`
  Allowed values: hostup, external, unknown
- `hostingIp` (string, required, nullable): IPv4 address the website records point at after the setup. `null` when it is not known. Example: `192.0.2.10`
- `classification` (object | null, required): What the domain's records point at now. `null` when the setup is not offered (`enabled: false`), when the domain has no DNS zone at Hostup, or when the zone could not be read.
- `classification.website` (string, required): `hosting`: this account. `parking`: Hostup's parking page. `stale`: a Hostup server that no longer hosts the domain. `missing`: no website record. `elsewhere`: another provider. `redirect`: a domain redirect is active. Example: `parking`
  Allowed values: hosting, parking, stale, missing, elsewhere, redirect
- `classification.mail` (string, required): `hosting`: this account. `missing`: no MX record. `elsewhere`: another provider. `disabled`: a null MX record says the domain takes no mail. Example: `missing`
  Allowed values: hosting, missing, elsewhere, disabled
- `classification.apex` (array<string>, required): Current A, AAAA, CNAME and ALIAS values of the bare domain. Example: `["192.0.2.80"]`
- `classification.www` (array<string>, required): Current A, AAAA, CNAME and ALIAS values of `www`. Example: `["192.0.2.80"]`
- `classification.mx` (array<string>, required): Current MX targets. `.` stands for a null MX record. Example: `[]`
- `classification.requiresChoice` (boolean, required): `true` when the website or email point elsewhere. Pointing them at the hosting account would replace them. Example: `false`
- `classification.recommendedPreference` (string, required): The choice that keeps the current services working. Example: `full`
  Allowed values: full, email-only, website-only, none
- `revision` (string, required, nullable): Fingerprint of the current records and nameservers. Send it in `POST`. `null` when `classification` is `null` or the nameservers could not be looked up. Example: `5f8c1d2e9a7b4c3d6e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d`
- `pendingChoice` (boolean, required): `true` while the domain waits for a setup choice. Example: `true`
- `publication` (string, required, nullable): `pending` while an applied setup is not in the zone yet. `done` on the first read after it is, `null` after that. `null` also when no setup was applied in the last hour. Example: `null`
  Allowed values: pending, done
- `canApply` (boolean, required): `true` when the setup is offered, the domain's DNS zone at Hostup was read and the hosting address is known. `POST` with a choice other than `none` also needs a `revision`. While `revision` is `null` the POST returns 503. Example: `true`

### Responses

#### 200 - Where the domain's website and email point and what the setup can do.
```json
{
  "domain": "example.com",
  "hostingName": "example.se",
  "currentMailAddresses": [],
  "enabled": true,
  "delegation": "hostup",
  "hostingIp": "192.0.2.10",
  "classification": {
    "website": "parking",
    "mail": "missing",
    "apex": [
      "192.0.2.80"
    ],
    "www": [
      "192.0.2.80"
    ],
    "mx": [],
    "requiresChoice": false,
    "recommendedPreference": "full"
  },
  "revision": "5f8c1d2e9a7b4c3d6e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d",
  "pendingChoice": true,
  "publication": null,
  "canApply": true
}
```

#### 400 - `domain` is missing or not a valid domain name.
```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"
}
```

#### 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"
}
```

#### 503 - The read failed. `code` is `domain_not_attached` when the domain is not the main, an addon or a parked domain of the account; retrying does not help then. It is `dns_read_unavailable` when the DNS could not be checked; try again later.
```json
{
  "type": "https://developer.hostup.se/errors/domain_not_attached",
  "title": "DNS setup",
  "status": 503,
  "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"
}
```
