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
accountIdstringrequiredacct_…).Body
domainstringrequiredexample.net or shop.example.com. Unicode IDN and punycode spellings are both accepted.dirstring/ or contain ... Omit it to use the default folder. The response gives the folder that was used.forcebooleandns_setup_choice_required. Send it only together with dnsSetupPreference. Alone it returns 400.dnsSetupIntentstringemail 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.dnsSetupPreferencestringfull: 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
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" }'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": "shop.example.com" }'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", "dnsSetupIntent": "email" }'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", "dnsSetupPreference": "none" }'Responses
201 The domain is added.
{ "domain": "shop.example.com", "kind": "sub", "documentRoot": "shop.example.com"}Response fields
domainstringkindstringaddon for a domain with its own site. sub for a subdomain of a domain on the account. One of addon, sub.documentRootstringErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The 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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The API key lacks a required scope or the hosting account is not active. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 409 | The 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. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | The 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. |