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

**Read hosting DNS setup state for a domain**

Read the current authoritative DNS of a domain attached to the shared-hosting account and classify where its website and email point, so a client can offer the same setup choice the client area offers after attaching a domain. Get `{accountId}` from `GET /api/v2/shared-hosting` `data[].id`; the domain must already be attached to the account (`GET /api/v2/shared-hosting/{accountId}/domains`). The response tells whether the setup can be applied (`canApply`), which setup the platform recommends, the `revision` that `POST` requires, and whether a previously applied setup has finished publishing. The same route also serves the DNS setup link sent by email: send `Authorization: DnsSetup <token>` instead of a session or API key and the response additionally carries `linkUsed`, `linkCompleted` and `linkPreference`. Responses are never cached.

### Related Endpoints

- `POST /api/v2/shared-hosting/{accountId}/domains/dns-setup`: Apply hosting DNS setup for a domain
- `GET /api/v2/shared-hosting/{accountId}/domains`: List hosting domains
- `POST /api/v2/shared-hosting/{accountId}/domains`: Add hosting domain

### Headers

- `Accept`: application/json
- `Authorization`: Bearer YOUR_API_KEY
- Required API scopes: `read:hosting`, `read:dns`, `console:services`

### Parameters

- `accountId` (path, string, required): Public shared-hosting account ID from `GET /api/v2/shared-hosting` `data[].id`. Do not invent this value; use the exact ID returned by the referenced API response. Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `domain` (query, string, required): Full domain name attached to the hosting account, without protocol or path. Example: `example.com`

### Request Example

```bash
curl -X GET "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains/dns-setup?domain=example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Response Schema

- `domain` (string, required) Example: `example.com`
- `hostingName` (string, required): The hosting account's main domain, as shown in the client area. Example: `example-hosting.se`
- `currentMailAddresses` (array<string>, required): IP addresses the domain's current MX hosts resolve to inside this zone; empty when mail is not hosted in it. Example: `[]`
- `enabled` (boolean, required): `false` when this hosting account's platform does not offer the setup action; `POST` then returns 409 `dns_not_enabled`. Example: `true`
- `delegation` (string, required): Where the domain's nameservers point. The choice can be prepared while delegation is still `external`; nothing is live until the nameservers move. Example: `hostup`
  Allowed values: hostup, external, unknown
- `hostingIp` (string, required, nullable): The address website records are pointed at when the setup is applied. Example: `185.113.11.42`
- `classification` (object, required, nullable): What the domain's current authoritative DNS points at. `null` when the zone could not be read.
- `revision` (string, required, nullable): Fingerprint of the current DNS records and nameservers. Send it back in `POST`; a mismatch returns 409 `dns_changed`. `null` when the zone could not be read. Example: `5f8c1d2e9a7b4c3d6e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d`
- `pendingChoice` (boolean, required): `true` while the platform is still waiting for the customer to choose a setup for this domain. Example: `true`
- `publication` (string, required, nullable): State of the last applied setup: `pending` until the zone matches the plan, `done` once it does, `null` when nothing was applied. Example: `null`
  Allowed values: pending, done
- `canApply` (boolean, required): `true` when the setup can be applied now: the action is enabled, the zone was read and a hosting address is known. Example: `true`
- `linkUsed` (boolean, optional): Only with a DNS setup link token: whether the link has been used before. Example: `false`
- `linkCompleted` (boolean, optional): Only with a DNS setup link token: whether the link's setup was already completed. Example: `false`
- `linkPreference` (string, optional, nullable): Only with a DNS setup link token: the preference the link was issued for, if any. Example: `null`
  Allowed values: full, email-only, website-only, none

### Responses

#### 200 - Current DNS setup state for the domain.
```json
{
  "domain": "example.com",
  "hostingName": "example-hosting.se",
  "currentMailAddresses": [],
  "enabled": true,
  "delegation": "hostup",
  "hostingIp": "185.113.11.42",
  "classification": {
    "website": "parking",
    "mail": "missing",
    "apex": [
      "185.113.11.0"
    ],
    "www": [
      "185.113.11.0"
    ],
    "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 - 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 - 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 domain is not attached to this hosting account.
```json
{
  "type": "https://developer.hostup.se/errors/domain_not_attached",
  "title": "DNS setup",
  "status": 409,
  "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"
}
```

#### 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": "Too many requests. Retry after the limit resets.",
  "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 DNS zone could not be read right now.
```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"
}
```