Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Apply the DNS setup of a hosting domain

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

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.

Authentication: An API key with the scopes write:hosting and write:dns and console:services. About keys and scopes

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Body

domainstringrequired
Main domain, addon domain or parked domain of the hosting account.
preferencestringrequired
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. One of full, email-only, website-only, none.
revisionstring
The revision from the latest GET. Needed for every choice except none. A missing or old value returns 409 dns_changed.

Example

POST /api/v2/shared-hosting/{accountId}/domains/dns-setup
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"
  }'

Responses

200 The choice is saved. Records are written for every choice except none.

Response 200
{
  "success": true,
  "domain": "example.com",
  "preference": "full",
  "status": "done"
}
Response fields
successboolean
Always true. One of true.
domainstring
The domain.
preferencestring
The saved choice. One of full, email-only, website-only, none.
statusstring
done when the records already match the setup. pending while they are still being published. One of done, pending.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400domain or preference is missing or invalid.
401Unauthorized. Authentication is required.
403The API key lacks a required scope or the hosting account is not active.
404Not found. The resource does not exist or is not owned by the caller.
409The 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).
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.
502The 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.
503The 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.

This page as MarkdownOpenAPI spec