Skip to content

Check a main domain change for web hosting

GET /api/v2/shared-hosting/{accountId}/actions/change-main-domain

Check whether the main domain of a web hosting account can be changed and what the change would do. Nothing is changed. Without domain the response covers the account: available and reason, the current mainDomain, the other domains on it and the mailboxes on the main domain. Send domain to check a new main domain as well. target then says whether it can be used, how each mailbox address changes and how its DNS would be set up. The new main domain can come from outside the account or be an addon domain already on it (promotableDomains). For an addon domain target.promotion describes the folder swap. That only works while the current main domain has no mailboxes or forwarders. The change is not available while the main domain has subdomains of its own. It is also not available on an account that is not active or not on cPanel. A domain registered with Hostup or with a DNS zone at Hostup must be on your own account. Make the change with POST /api/v2/shared-hosting/{accountId}/actions/change-main-domain.

Authentication: An API key with the scope read:hosting. Also console:services: always needed. Also read:dns: only when you send domain. About keys and scopes

Request

Path parameters

accountIdstringrequired
The web hosting account ID (acct_…).

Query parameters

domainstring
A domain to check as the new main domain, without www..

Example

GET /api/v2/shared-hosting/{accountId}/actions/change-main-domain
curl "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The account’s main domain state. With domain, also the check of that domain.

{
"available": true,
"reason": null,
"mainDomain": "example.com",
"otherDomains": [],
"promotableDomains": [],
"emailAccounts": [
"info@example.com"
],
"actions": {
"canKeepPreviousDomain": {
"allowed": true,
"reason": null
}
},
"target": {
"domain": "shop.example.com",
"available": true,
"reason": null,
"emailAccountChanges": [
{
"current": "info@example.com",
"afterChange": "info@example.se"
}
],
"dnsSetup": {
"usesHostupNameservers": true,
"managedRecordsRead": true,
"nameservers": [
"primary.ns.hostup.se",
"secondary.ns.hostup.se"
],
"hasThirdPartyWebsiteRecords": false,
"hasThirdPartyMailRecords": false,
"requiresChoice": false,
"recommendedPreference": "full",
"records": {
"website": [],
"mail": []
},
"options": []
},
"promotion": null
}
}
Response fields
availableboolean
Whether the main domain of this account can be changed now.
reasonstring or null
Why the change is not available. Null when available is true.
mainDomainstring or null
The account’s main domain now.
otherDomainsarray of string
The other domains on the account: addon domains, aliases and subdomains. They stay on the account through the change.
promotableDomainsarray of string
Addon domains that can become the main domain. Send one as domain to see target.promotion.
emailAccountsarray of any or null
Mailboxes on the main domain. They get addresses on the new main domain. Null when they could not be read.
actionsobject
canKeepPreviousDomainobject
Whether POST can keep the old main domain with keepPreviousDomain: true. Keeping it uses one addon domain on the plan.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
targetobject or null
The check of the domain you sent. Null without domain.

Errors

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

400domain is not a full domain name or starts with www..
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller.
409Conflict. code is account_not_eligible_cpanel.
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 account’s domains could not be read right now. Try again later.