Add hosting addon domain

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

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 tolerated for compatibility but must be accompanied by dnsSetupPreference; sending force without dnsSetupPreference returns 400 invalid_request.

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

Authenticate with an API key in the Authorization: Bearer <token> header.

Context

Related endpoints

GET /api/v2/shared-hosting/{accountId}/domains List hosting domains DELETE /api/v2/shared-hosting/{accountId}/domains Remove hosting addon domain GET /api/v2/shared-hosting/{accountId} Get shared-hosting account

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

Authorization Bearer <token>

Accept application/json

Content-Type application/json

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. Must be sent together with dnsSetupPreference; force alone returns 400 invalid_request.

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. 3 fields

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. 10 fields

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. 10 fields

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. 10 fields

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. 10 fields

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. 10 fields

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. 10 fields

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. 10 fields

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"
}

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "addon"
      ]
    },
    "documentRoot": {
      "type": "string"
    }
  }
}

Request Body Add addon domain

{
  "domain": "shop.example.com",
  "dir": "shop.example.com"
}