Add hosting addon domain

Provision an addon domain inside a shared-hosting account that supports cPanel control-panel domain management. Get {accountId} from GET /api/v2/shared-hosting data[].id; this path parameter is named accountId, not id. Send the full hostname in domain; do not pass a raw domain name as {accountId} and do…

Read full description Hide full description

Provision an addon domain inside a shared-hosting account that supports cPanel control-panel domain management. Get {accountId} from GET /api/v2/shared-hosting data[].id; this path parameter is named accountId, not id. Send the full hostname in domain; do not pass a raw domain name as {accountId} and do not use the retired subdomain field. There is no /api/v2/shared-hosting/{accountId}/addon-domains route; use this /domains route for addon domains. dir is optional and must be a safe relative path. If the domain already uses HostUp-managed nameservers and existing website or email DNS records appear to point elsewhere, the endpoint returns dns_setup_choice_required with dnsSetup.options and a recovery.suggestedBody; retry with one dnsSetupPreference value (full, email-only, website-only, or none). force: true is accepted for older clients but the explicit dnsSetupPreference is the confirmation signal. Non-full choices also save a DNS sync restriction before the cPanel mutation so preserved website or mail record types are not overwritten by the control-panel DNS sync. If this returns domain_not_ready, the domain is registered too recently or its nameservers are not publicly visible yet; for .se and .nu domains this usually resolves within 1-2 hours after registration or a nameserver change, then callers can retry. If this returns account_not_eligible_cpanel, the selected hosting account uses HostUp's legacy control panel. Use the control panel SSO link to add the domain manually, or open a support ticket using a slug from GET /api/v2/support/departments and ask to migrate the account to a newer cPanel-backed plan.

Web Hosting Hosting Accounts

Authentication

Required API scopes: write:hostingconsole:services

Use Authorization: Bearer <token> for API keys. Dashboard sessions may also use hostup_session.

Context

Path Parameters

accountId string required Example: acct_01hxa3b4c5d6e7f8g9h0j1k2m3

Public shared-hosting account ID. Get it from GET /api/v2/shared-hosting `data[].id`. Do not invent this value; use the exact ID returned by the referenced API response.

Headers

Accept Example
Content-Type Example

Body

required
application/json
domain string required · Example: shop.example.com
dir string · Example: shop.example.com

Relative directory under the hosting account. Must not start with `/` and must not contain `..`.

force boolean · Example: true

Compatibility flag for clients retrying after `dns_setup_choice_required`. The selected `dnsSetupPreference` is the actual confirmation signal.

dnsSetupPreference string · enum · Example: website-only

DNS handling selected after a `dns_setup_choice_required` blocker. `full` means website and email can use this hosting, `email-only` keeps the current website, `website-only` keeps current email, and `none` keeps existing DNS unchanged. When the domain uses HostUp-managed nameservers, non-`full` choices restrict which record types cPanel DNS sync may change.

full
email-only
website-only
none

Responses

201 Addon domain added.
domain string required
kind string · enum required
addon
documentRoot string required
400 Invalid request body, for example an invalid `domain` hostname or unsafe `dir` path.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
401 Unauthorized. Authentication is required.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
403 Forbidden. The caller lacks a required scope or does not own the resource.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
404 Not found. The resource does not exist or is not owned by the caller.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
409 The domain cannot be added in the current state, for example because it is not DNS-ready yet, needs an explicit DNS handling choice, conflicts with an existing hosting entry, or the hosting account is not eligible for addon-domain management through this API.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
429 Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
500 Internal error. Retry later or contact support if the issue persists.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
POST https://cloud.hostup.se/api/v2/shared-hosting/{accountId}/domains
For AI assistants
View as Markdown
cURL 
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com",
    "dir": "shop.example.com"
  }'
Response 
{
  "domain": "shop.example.com",
  "kind": "addon",
  "documentRoot": "shop.example.com"
}
Request Body Add addon domain 
{
  "domain": "shop.example.com",
  "dir": "shop.example.com"
}