Skip to content

Add a domain to web hosting

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

Adds a domain or a subdomain to the web hosting account. Send the full hostname in domain. A name below a domain already on the account (main, addon, parked or subdomain) becomes a subdomain in that domain’s DNS zone. Any other domain becomes an addon domain. Check actions.canAddAddon on GET /api/v2/shared-hosting/{accountId}/domains first.

A new addon domain must be registered and have public nameservers. Otherwise the call returns 409 domain_not_ready with recovery.retryAfterSeconds. For .se and .nu domains this usually takes 1-2 hours after registration or a nameserver change.

When the domain uses Hostup’s nameservers and has website or email records that point elsewhere, the call returns 409 dns_setup_choice_required. The problem lists the records, the four choices and recovery.suggestedBody. Send the request again with dnsSetupPreference. An explicit dnsSetupPreference is the confirmation signal. When no choice is needed, the website and email of a domain on Hostup’s nameservers are pointed at the hosting account.

domain_conflict means the domain is already on a hosting account. An account on Hostup’s previous hosting platform returns 409 account_not_eligible_cpanel. Support moves such an account to cPanel at no charge.

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

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Body

domainstringrequired
Full hostname to add, for example example.net or shop.example.com. Unicode IDN and punycode spellings are both accepted.
dirstring
Folder for the site, relative to the account’s home directory. It must not start with / or contain ... Omit it to use the default folder. The response gives the folder that was used.
forceboolean
Compatibility flag for clients retrying after dns_setup_choice_required. Send it only together with dnsSetupPreference. Alone it returns 400.
dnsSetupIntentstring
email when the domain is added to use email on the hosting account. When the domain uses other nameservers or its records could not be read, the setup then keeps the current website records. It is not a confirmation. Records that point elsewhere still return dns_setup_choice_required. One of email.
dnsSetupPreferencestring
Which services move to the hosting account. full: website and email. email-only: email, the current website stays. website-only: the website, the current email stays. none: no DNS changes. The choices other than full keep the matching existing records from being overwritten. One of full, email-only, website-only, none.

Example

POST /api/v2/shared-hosting/{accountId}/domains
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "example.net",
"dir": "example.net"
}'

Responses

201 The domain is added.

Response 201
{
"domain": "shop.example.com",
"kind": "sub",
"documentRoot": "shop.example.com"
}
Response fields
domainstring
The domain as added. IDNs are in Unicode form.
kindstring
addon for a domain with its own site. sub for a subdomain of a domain on the account. One of addon, sub.
documentRootstring
Folder that serves the site, relative to the account’s home directory.

Errors

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

400The body is invalid: domain is not a full hostname, dir is not a safe relative path, dnsSetupPreference or dnsSetupIntent has an unknown value, force came without dnsSetupPreference or the body has the retired subdomain field.
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 domain cannot be added now. code says why. domain_not_ready: the domain has no public nameservers yet. Try again after recovery.retryAfterSeconds. dns_setup_choice_required: send the request again with dnsSetupPreference. domain_conflict: the domain is already on a hosting account. dns_conflict: the account already has a DNS entry that clashes with this name. account_not_eligible_cpanel: the account is on Hostup’s previous hosting platform.
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 domain could not be added on the server. The same status comes when the DNS setup choice could not be saved. The domain is then not added.