Skip to content

cPanel accounts

Account scope required: include the X-Auth-Account header with your Account ID. Reads require the cpanel:read OAuth scope. Every write on this page is unavailable via OAuth and answers 403 endpoint not available via OAuth for any OAuth token, whatever scopes it carries; use a session or API-key credential. See OAuth and Authentication.

Availability is enabled per workspace

A workspace that is not a cPanel customer gets 403 cpanel_not_enabled on every endpoint on this page, reads included.

Writes use the same cart and checkout as the dashboard and return 202 Accepted with the shared cart polling envelope rather than a finished result. See Async Operations. Reads can lag the hosting platform by a few minutes (see local_package below).

A cPanel account is addressed by its cPanel username (letters, digits and underscores), not a GUID: GET /api/cpanel_accounts/acmeco01.

Request guards

Applied in this order. The first one that fails answers the request.

Applies to Condition Response
all X-Auth-Account missing or not resolvable 400 missing_account
all cPanel hosting is not configured on the platform 503 cpanel_unavailable
all workspace is not a cPanel customer 403 cpanel_not_enabled
create, update, destroy credential has no user (a system Account-bearer API key) 401 user_required
create, update workspace is on a trial 403 trial_account
show, update, destroy username unknown, or not yours 404 account_not_found
show, update, destroy the account could not be looked up right now, or the account is unavailable (see List cPanel Accounts) 503 cpanel_unavailable
create, update user cannot manage billing on the owning workspace 403 not_authorized
destroy user cannot manage service lifecycle on the owning workspace 403 not_authorized
update the account is a mail-only account 422 resize_not_supported
update account is pending deletion 403 pending_deletion
update account was suspended by staff 403 account_suspended
update account is suspended for an unpaid invoice 402 service_suspended
  • Role checks run against the workspace that owns the account, which is not always the workspace in X-Auth-Account.
  • An unauthorized username answers 404 account_not_found, not 403.
  • The pending_deletion body also carries delete_scheduled_at.
  • show is not state-gated: a suspended or pending-deletion account can still be read.
  • A mail-only account (kind: "mail_only") can be listed, viewed, canceled and purged. Resize answers 422 resize_not_supported, and the password, domain and session endpoints answer 404 account_not_found.

Per-account endpoints

The password, purge, domain and session endpoints run the first four guards above (missing_account, cpanel_unavailable, cpanel_not_enabled, then the lookup that answers 404 account_not_found). On top of that:

Endpoint Needs a user Trial Role on the owning workspace Locked while pending deletion
GET …/domains no allowed none no
POST …/domains yes rejected billing management yes
PATCH …/domains/{domain} yes rejected billing management yes
DELETE …/domains/{domain} yes rejected billing management yes
PATCH …/password yes rejected billing management yes
POST …/purge yes rejected service lifecycle n/a — it requires pending deletion
POST …/session yes rejected edit no

"Needs a user" means a system Account-bearer API key is refused with 401 user_required; a trial workspace gets 403 trial_account; a failed role check gets 403 not_authorized. These endpoints have no account_suspended or service_suspended answer.

A pending-deletion account is locked

Changing the password or adding or removing a domain on an account scheduled for deletion answers 403 pending_deletion, with delete_scheduled_at in the body. Restoring the account is a dashboard action (see Still dashboard-only), so an unattended job should alert on this rather than retry.

There is no step-up authentication on the API. Password changes, purges and domain removals need a session or API-key credential (never OAuth) plus the role above.

List cPanel Accounts

GET /api/cpanel_accounts

Params (optional)
  • page: Integer | page number (default: 1)
  • per_page: Integer | records per page (default: 50, max: 100)
  • q: String | case-insensitive substring search across username, server hostname, primary domain, and add-on/alias domains
Returned Params
  • cpanel_accounts: Array
    • username: String
    • kind: String | hosting or mail_only. A mail-only account has a null package.code and 0 disk figures. Omitted on provisioning and unavailable rows
    • primary_domain: String | null when the account has no main domain recorded yet
    • package: Object | the account's current package
      • code: String | the current package code, uppercased. Commonly S, M, L or XL, but not limited to those: other codes appear here verbatim. null when the account has no package
      • key: String | mini, basic, pro, max; null for a package not in the current catalogue
      • label: String | e.g. Pro; falls back to the raw code
    • local_package: String | package code. Present only while a create or resize is still taking effect, when package has not caught up with the package we last set. Omitted the rest of the time
    • disk: Object
      • used_mb: Integer
      • quota_mb: Integer
    • server: String | normalized hostname, or null
    • mailbox_count: Integer
    • addon_domain_count: Integer
    • state: String | active, provisioning, dunning_suspended, admin_suspended, pending_deletion, unavailable
    • delete_scheduled_at: DateTime | null unless the account is scheduled for deletion
    • subscription: Object | null when the account has no local subscription
      • id: String | subscription GUID
      • status: String
      • term: String | the subscription's current term
    • account: Object | the owning workspace. Omitted when the account has no local record (a customer-level grant)
      • id: String
      • name: String

state and the provisioning window

state is derived, and pending_deletion wins over both suspension flags — it is the terminal state and the only one that changes which operations are possible. An account you just ordered appears as provisioning until it is ready; those rows are built from the local record, so disk.used_mb / disk.quota_mb and server are null, mailbox_count and addon_domain_count are 0, local_package is never present, and package reflects the package you ordered rather than a live reading.

unavailable accounts

An unavailable row is an account of yours that cannot be matched to exactly one account on the hosting platform. It is shaped like a provisioning row, is not counted as an active account, and every per-account endpoint answers 503 cpanel_unavailable for it until support resolves it.

The response carries no total-count metadata; page until cpanel_accounts comes back empty.

What is listed

Hosting and mail-only accounts appear; tell them apart with kind. Accounts whose local record was already purged are not listed, even if the the platform still lists them.

Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 503 cpanel_unavailable | the account list could not be read; retry

This endpoint fails loudly

When the account list can't be read, the API reports 503 cpanel_unavailable rather than an empty list, so a client never mistakes an outage for "you have no cPanel accounts". Retry rather than reconciling against an empty list.


View a cPanel Account

GET /api/cpanel_accounts/:username

Returns the same object as the list, under a cpanel_account key.

Returned Params

If a count or the primary domain can't be read, the request still succeeds: mailbox_count comes back as 0 and primary_domain falls back to the domain recorded locally.

Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 503 cpanel_unavailable | the account list could not be read; retry

Order a cPanel Account

POST /api/cpanel_accounts

This charges immediately

cPanel hosting is payment-first. This endpoint charges the billing account's saved default payment method off-session and provisions asynchronously. There is no synchronous success branch and no checkout redirect — it always returns 202 Accepted. The account (username and a generated password) is created once payment settles.

Requires a user-scoped credential; a system Account-bearer API key returns 401 user_required. Trial workspaces return 403 trial_account. Not available via OAuth.

Params
  • package: String (required) | package key (mini, basic, pro, max) or package code (S, M, L, XL)
  • term: String (optional) | monthly or annual; defaults to the workspace's billing term
  • domain: String (optional) | an existing domain, registered with us or elsewhere, used as the account's main domain. Omit it and the account gets a temporary domain; until you set its main domain in the dashboard, adding domains to it returns main_domain_temporary
  • callback: Object (optional) | outbound notification when the async work completes — same contract as POST /api/orders, see Callbacks
    • authorization: String | full Authorization header value. Example: Bearer 12345
    • url: String | fully qualified URL

Registering a new domain is a separate order

domain must already be a domain in the workspace and actually registered — a name merely attached to a site is not enough. Registering a domain in the same cart is not supported here; call POST /api/orders/domain first, then order the hosting account.

curl -X POST https://my.cloudpress.com/api/cpanel_accounts \
  -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  -H "X-Auth-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"package": "pro", "term": "monthly", "domain": "acmeco.com"}'
Returned Params (always 202 Accepted)
  • status: String | "accepted"
  • cart: Object
    • token: String
    • status: String | the cart's own status. Commonly active, processing or checked_out; while you are polling it can also become awaiting_provisioning (payment captured, provisioning parked) or expired (the cart was failed or abandoned), so treat the list as examples rather than a closed set
    • rollup_status: String
    • poll_url: String | absolute URL, e.g. https://your-instance/api/carts/<token>
  • payment: Object
    • status: String | processing, succeeded, awaiting_authentication; awaiting_bank_transfer or failed on a bank-transfer order; on_next_invoice on a post-pay order — see Payment lanes
    • method_type: String | the resolved payment-method type. Commonly card or sepa_debit, but other types can appear — us_bank_account, bacs_debit, acss_debit, au_becs_debit, customer_balance, ideal and others are all possible. null until it can be resolved
    • hosted_invoice_url: String | null
  • orders: Array | each { id, status, poll_url }; empty during the async window

Poll cart.poll_url to discover the order, then each orders[].poll_url until its status is terminal. orders is empty at first when the account is charged by card or bank transfer: the order is created after the charge settles. Payment scenarios (3DS parking, SEPA, credit balance, decline) behave exactly as documented for PATCH /api/sites/:id.

Errors

Authorization / gating:

  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | trial workspaces cannot buy cPanel hosting
  • 403 not_authorized | user cannot manage billing on this workspace

Validation (400, nothing charged, no order created):

  • unknown_package | package is not a known package key or package code
  • invalid_term | term is not monthly or annual
  • product_unavailable | the requested package is not on this billing plan, or is archived (no longer on sale)
  • no_default_payment_method | the billing account is not ready to charge
  • invalid_domain | domain is not a valid domain name
  • billing_details_incomplete | a workspace billed by bank transfer whose billing contact is incomplete

Processing (422):

  • no_price_for_plan | no price for the requested package and term
  • domain_not_registered | domain is not registered anywhere
  • domain_in_use | domain is already live on another hosting account
  • domain_dns_zone_exists | the DNS zone for domain belongs to a workspace outside your billing family. Nothing is charged
  • cart_add_failed | the cart rejected the item
  • cart_pay_failed | the off-session charge could not be started

  • 503 cpanel_unavailable | cPanel is not configured, or domain could not be verified against the hosting servers

The checkout-lane refusals listed under Payment lanes apply too.


Payment lanes

The payment lane is decided per order, for ordering and resizing alike. Read payment (and, on a post-pay order, billing) in the response; Orders explains the lanes and what to do about each refusal.

Refusal codes: 400 billing_details_incomplete; 403 billing_permission_required; 409 bank_transfer_in_progress, bank_transfer_busy, postpay_busy; 422 outstanding_balance_exceeded, in_flight_limit_exceeded, payer_in_dunning, recent_dispute, instant_payment_method_required, bank_transfer_refused, bank_transfer_failed, postpay_route_changed, postpay_pay_open_invoices, postpay_contact_support, postpay_payment_in_progress, postpay_failed, and on a resize postpay_change_refused and postpay_add_payment_method.


Change Package (Resize)

PATCH /api/cpanel_accounts/:username

Changes the package and re-prorates billing. For a workspace billed by card, the proration is charged to the saved payment method, as for a WordPress site resize; for a workspace on a plan not billed by card, the package change is applied as an order with no charge. Returns 202 Accepted with the same cart envelope as Order a cPanel Account.

The term never changes

A resize is always priced on the live subscription's current term. There is no term, domain or callback param here, so this endpoint never returns invalid_term, invalid_domain or domain_in_use.

Params
  • package: String (required) | target package key (mini, basic, pro, max) or package code (S, M, L, XL)
Returned Params (always 202 Accepted)

Identical envelope to Order a cPanel Account:

  • status: String | "accepted"
  • cart: Object | { token, status, rollup_status, poll_url }
  • payment: Object | { status, method_type, hosted_invoice_url }
  • orders: Array | [{ id, status, poll_url }] (empty during the async window)

Do not retry a resize blind

A package change is claimed before any money moves, so a second PATCH sent while the first is still applying is refused with 409 resize_in_flight rather than charging a second proration. "Already on that package" is checked against both the account's current package and the package last set, so a change still taking effect counts too. If a request times out, poll the cart or re-read the account instead of re-sending the PATCH.

Downgrades must fit current usage

A smaller package is refused with 422 usage_exceeds_package when the account's current disk, mailbox or add-on-domain usage exceeds what the target includes — otherwise the account would be left over quota. Reduce usage first. Upgrades are never usage-checked, so an account sitting above today's caps on an older package can always move up.

Errors

Authorization / gating:

  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | trial workspaces cannot resize
  • 403 not_authorized | user cannot manage billing on the owning workspace
  • 404 account_not_found | unknown username, or not accessible to this credential

Account state:

  • 403 pending_deletion | the account is pending deletion and locked — recover it first (body carries delete_scheduled_at)
  • 403 account_suspended | suspended by staff; contact support
  • 402 service_suspended | suspended for an unpaid invoice

Validation (400):

  • unknown_package | package is not a known package key or package code
  • product_unavailable | the target package is not on this billing plan
  • no_default_payment_method | a saved default payment method is required to charge the proration off-session, and none was found
  • billing_details_incomplete | a workspace billed by bank transfer whose billing contact is incomplete

Conflict (409):

  • resize_in_flight | an earlier package change is still being applied

Processing (422):

  • resize_not_supported | a mail-only account — package changes are not offered, only cancellation
  • same_package | already on that package
  • usage_exceeds_package | the target package is smaller than current disk / mailbox / add-on-domain usage
  • no_price_for_plan | no price for the target package on the subscription's term
  • no_billing_subscription | the account has no billing subscription to prorate against; contact support
  • subscription_not_proratable | the cart could not be staged as a proration; refused rather than charged as a brand-new purchase
  • cart_add_failed | the cart rejected the item
  • cart_pay_failed | the off-session charge could not be started

  • 503 cpanel_unavailable | cPanel is not configured, or the account could not be looked up

The checkout-lane refusals listed under Payment lanes apply too.


Cancel a cPanel Account

DELETE /api/cpanel_accounts/:username

Soft-delete. This stamps the retention window, cancels billing — stopping renewals and crediting the unused first term — and suspends the account. The account stays recoverable from the CloudPress dashboard until delete_scheduled_at, when it is removed permanently.

Works for hosting and mail-only accounts alike.

Gated on service-lifecycle role membership of the owning workspace. Staff who are not members of the workspace are excluded, and there is no API step-up authentication that could stand in for the dashboard's re-confirm-identity prompt.

Returns 202 Accepted.

Returned Params
  • status: String | "pending_deletion"
  • username: String
  • delete_scheduled_at: DateTime | the frozen purge date; recoverable until then
Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 not_authorized | user cannot manage service lifecycle on the owning workspace
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 422 account_already_purged | the account is still listed but has already been purged
  • 422 account_delete_failed | the account could not be scheduled for deletion
  • 503 cpanel_unavailable | cPanel is not configured, or the account's server credentials could not be resolved

Purge a Pending-Deletion Account

POST /api/cpanel_accounts/:username/purge

Permanent and irreversible. Works for hosting and mail-only accounts. Releases the account and its data now instead of at delete_scheduled_at. This only shortens a retention window that cancelling already opened — the account must already be pending deletion, and there is no combined cancel-and-purge path, so a single mistaken call can never destroy a live account.

Returns 202 Accepted. The removal itself runs in the background, but the account leaves GET /api/cpanel_accounts immediately — its absence from that list is the signal to poll for, and there is no task to follow.

Gated on service-lifecycle role membership of the owning workspace, and unavailable via OAuth.

Returned Params
  • status: String | "purging"
  • username: String
Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | the workspace is on a trial
  • 403 not_authorized | user cannot manage service lifecycle on the owning workspace
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 422 account_not_pending_deletion | the account is live; cancel it first
  • 503 cpanel_unavailable | cPanel is not configured, or the account could not be looked up

Change the cPanel Password

PATCH /api/cpanel_accounts/:username/password

Sets the password on the hosting account immediately — there is no async window, so the old password stops working at once.

This is not a session kill switch

Whether cPanel also tears down sessions already open under the old password is cPanel's own behaviour and is not guaranteed here. If you are rotating because a credential leaked, do not treat this call as proof the leaked session is closed.

Password strength is enforced by the hosting server, not by CloudPress; a value it rejects comes back as password_change_failed. The failure text is deliberately generic — the server's own message is logged rather than echoed.

Params
  • password: String (required) | the new password. There is no password_confirmation — that is a form affordance, not an API contract
Returned Params
  • status: String | "changed"
  • username: String
Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | the workspace is on a trial
  • 403 not_authorized | user cannot manage billing on the owning workspace
  • 403 pending_deletion | the account is scheduled for deletion; restore it first
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 422 password_blank | no password supplied
  • 422 password_change_failed | the server refused the value, usually on strength
  • 503 cpanel_unavailable | cPanel is not configured, or the account's server credentials could not be resolved

List Account Domains

GET /api/cpanel_accounts/:username/domains

The aliases, subdomains and add-on domains attached to one account. Read live from the hosting server (falling back to our last known data), so a domain added through this API appears as soon as the server has finished building it.

Each row carries two type fields. type is the raw value the server reports and is schema-dependent — main, addon, sub, parked, alias and other spellings all occur. domain_type is the normalized vocabulary this API speaks and is what the rest of this section means by a domain's kind; it is null for the account's main domain, which cannot be removed.

Returned Params
  • domains: Array<Object>
    • name: String
    • type: String | the raw type the hosting server reports; null if it reports none
    • domain_type: String | parked, subdomain or addon; null for the main domain
    • document_root: String | the absolute path the domain serves files from, e.g. /home/acmeco01/public_html/shop. An alias reports its main domain's root. null when it could not be read
  • usage: Object | per-kind counters and the package's caps
    • addon: Object
      • count: Integer
      • limit: Integer | the numeric cap; null when unlimited or unknown
      • unlimited: Boolean | true only when the server actually said unlimited
      • at_limit: Boolean | true only against a real numeric cap, so an unknown limit never blocks
    • alias: Object | same shape as addon
    • subdomain: Object | same shape as addon

document_root can lag a change made directly in cPanel by up to ten minutes.

limit: null is ambiguous on purpose

A null limit means either "unlimited" or "we could not read the cap" — unlimited is the field that distinguishes them. Branch on at_limit, which is only ever true against a cap that is genuinely known.

Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 503 cpanel_unavailable | cPanel is not configured, or the domain list could not be read

Add a Domain

POST /api/cpanel_accounts/:username/domains

Which parameters are required depends on domain_type:

Pass the full hostname in domain. It must already be registered and owned by this workspace — a name that is not answers the deliberately generic domain_not_eligible rather than explaining which half failed, so this cannot be used to probe how a domain is known on the platform.

An alias's share target is not a parameter; it always resolves server-side to the account's primary domain.

Pass label (a single DNS label, no dots) and rootdomain. The parent must be one of this account's own domains — its main, add-on or parked/alias domains are all eligible.

Returns 202 Accepted, not 201, and the difference matters: the hosting server reports success before the vhost and zone rebuild finishes, so the domain can be missing from List Account Domains for a short while afterwards. Poll that list for the name rather than treating the response as proof the domain is live.

Params
  • domain_type: String (required) | parked, subdomain or addon
  • domain: String (required for parked and addon) | the full hostname
  • label: String (required for subdomain) | a single DNS label, no dots
  • rootdomain: String (required for subdomain) | the parent domain
  • dir: String (optional, subdomain and addon) | document root
  • connect_method: String (optional, parked and addon) | how the domain's DNS is connected: zone, nameservers or a_record; see below
  • seed_dns: Boolean (optional, legacy) | false is the same as connect_method: "a_record". Ignored when connect_method is given
  • mail: Boolean (optional, parked and addon; default false) | also write the domain's mail records. Ignored for a domain a Mailspace serves
  • replace_records: Boolean (optional; default false) | replace existing DNS records that collide with the ones this domain needs. Without it, a collision answers conflicts_found
  • approved_conflicts: Array<String> (optional, with replace_records) | the record_guid values from a conflicts_found answer that may be replaced. Any other collision answers conflicts_found again
Returned Params
  • status: String | "accepted"
  • domain: String
  • domain_type: String

How the DNS is connected

connect_method applies to a parked or add-on domain:

  • zone writes the records into this workspace's existing DNS zone for the domain.
  • nameservers means the domain is moving to CloudPress's nameservers; the zone is created if there is none. Only for a registrable domain (example.com), not a name under one (shop.example.com).
  • a_record means you keep your DNS elsewhere and point an A record at the server yourself. No DNS is written.

Without connect_method, DNS is written only when the domain is on our nameservers or this workspace hosts its zone. A subdomain gets its address records in its parent's zone when this workspace hosts it.

Records this API did not write are never changed or deleted unless you pass replace_records: true.

Colliding DNS records refuse the add

If records the domain needs collide with existing ones and you did not pass replace_records: true, the add answers 422 conflicts_found and nothing is changed, not even in cPanel. conflicts lists the records in the way (record_guid, type, host, value, site_name, managed_by). To replace them, retry with replace_records: true and approved_conflicts.

Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | the workspace is on a trial
  • 403 not_authorized | user cannot manage billing on the owning workspace
  • 403 pending_deletion | the account is scheduled for deletion; restore it first
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 422 invalid_domain_type | domain_type is not one of the three
  • 422 domain_blank | no domain supplied
  • 422 invalid_hostname | domain is not a valid hostname
  • 422 label_blank | no label supplied for a subdomain
  • 422 invalid_label | label is not a valid DNS label
  • 422 rootdomain_blank | no rootdomain supplied for a subdomain
  • 422 invalid_parent_domain | the parent is not one of this account's own domains
  • 422 domain_not_eligible | the domain is not registered to this workspace, or cannot be added here
  • 422 domain_already_on_account | the domain is already on this account
  • 422 domain_on_other_own_account | the domain is on another of this workspace's cPanel accounts; the body adds holder_username. Remove it there first
  • 422 addon_domain_limit_reached | the package's add-on cap is reached
  • 422 alias_domain_limit_reached | the package's alias cap is reached
  • 422 main_domain_temporary | the account still has its temporary main domain; set its main domain in the dashboard first
  • 422 domain_create_failed | the hosting server refused the change
  • 422 invalid_connect_method | connect_method is not zone, nameservers or a_record, or nameservers was given for a name under a registrable domain
  • 422 conflicts_found | existing DNS records collide with the records the domain needs; the body adds conflicts. See above
  • 503 cpanel_unavailable | cPanel is not configured, or the server could not be reached

Change a Domain's Document Root

PATCH /api/cpanel_accounts/:username/domains/:domain

Points an add-on domain or a subdomain at a different folder. :domain is a domain name on this account (otherwise 404 domain_not_found). The main domain and aliases cannot be changed (422 document_root_not_editable). PUT works the same.

The folder must already exist and be a plain directory (not a symlink). Nothing is created or moved; the domain serves the new folder immediately. Other domains that share the same configuration move with it and are listed in also_affected.

Requires a user, billing management on the owning workspace, and a credential that is not OAuth, like the other writes on this page.

Params
  • document_root: String (required) | the new root relative to the account's home directory, e.g. public_html/shop. The home directory itself, absolute paths, hidden folders and cPanel's own folders (such as mail or ssl) are refused with invalid_document_root
Returned Params (200 OK)
  • status: String | "updated", or "unchanged" when it already pointed there
  • domain: String
  • document_root: String | the new root, absolute (e.g. /home/acmeco01/public_html/shop)
  • previous_document_root: String | the root before the change, absolute
  • also_affected: Array<String> | other domains that share the changed configuration
Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | the workspace is on a trial
  • 403 not_authorized | user cannot manage billing on the owning workspace
  • 403 pending_deletion | the account is scheduled for deletion; restore it first
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 404 domain_not_found | the domain is not on this account
  • 422 document_root_not_editable | the domain is the main domain or an alias
  • 422 invalid_document_root | the value is not a folder inside the account's home directory, given relative to it
  • 422 document_root_not_found | the folder does not exist on the account, or is not a plain directory. Create it first
  • 422 document_root_update_failed | cPanel did not accept the new document root
  • 503 cpanel_unavailable | cPanel is not configured, or the server could not be reached

Remove a Domain

DELETE /api/cpanel_accounts/:username/domains/:domain

:domain is the domain name, not an ID. It must be one of this account's own domains; anything else answers 404 domain_not_found — the same answer an entirely unknown name gets, so this cannot be used to probe what lives elsewhere on the platform.

The kind of removal is derived server-side from the domain's own listed row. There is no domain_type parameter and one supplied is ignored. The account's main domain cannot be removed (invalid_domain_type) — cancel the account instead.

DNS cleanup

Removing a domain also takes back the DNS records this API wrote for it, and only those. Anything else in the zone, and the zone itself, stays in place.

Params (optional)
  • rootdomain: String | a hint for a subdomain's parent. Honoured only when it is genuinely one of this account's own parents; otherwise the server-side derivation wins
Returned Params
  • status: String | "removed"
  • domain: String
  • domain_type: String
Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | the workspace is on a trial
  • 403 not_authorized | user cannot manage billing on the owning workspace
  • 403 pending_deletion | the account is scheduled for deletion; restore it first
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 404 domain_not_found | the domain is not on this account
  • 422 invalid_domain_type | the domain is the account's main domain, or its kind could not be derived
  • 422 temporary_domain_not_removable | the domain is a temporary domain, which cannot be removed
  • 422 domain_remove_failed | the hosting server refused the change
  • 503 cpanel_unavailable | cPanel is not configured, or the server could not be reached

Open a cPanel Session

POST /api/cpanel_accounts/:username/session

Mints a one-time, short-lived login URL for the account's cPanel interface. Like POST /api/sites/{id}/sso, it returns the URL and never redirects, so no response from this API is ever a cross-host 302 and the caller decides what to do with it.

Treat the URL as a credential

Anyone holding it is logged in as the cPanel account. Do not log it, cache it, or put it in a URL that gets recorded.

The returned URL is checked to be on the same hosting server the request was issued to. One that is not is refused with sso_url_rejected and never handed back, so a misconfigured or compromised server cannot turn this into an open redirect.

Gated on edit permission on the owning workspace — view-only members cannot open a session.

Returned Params
  • url: String | the one-time login URL
Errors
  • 400 missing_account | no workspace resolved from X-Auth-Account
  • 401 user_required | system Account-bearer key (no user)
  • 403 cpanel_not_enabled | cPanel hosting is not enabled for this workspace
  • 403 trial_account | the workspace is on a trial
  • 403 not_authorized | user cannot edit the owning workspace
  • 404 account_not_found | unknown username, or not accessible to this credential
  • 422 sso_url_rejected | the hosting server returned a login URL that could not be trusted
  • 503 cpanel_unavailable | the server could not be reached, or a session could not be created

Still dashboard-only

Restoring an account that is pending deletion has no API route. Cancelling and purging are both scriptable, but undoing a cancellation is a re-purchase: it builds a cart for the package and settles a payment, then revives the existing hosting account. Purging is irreversible, so an unattended cleanup job should treat every cancellation it issues as final.

Need it on the API?

Tell us what you're automating.