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
404account_not_found, not403. - The
pending_deletionbody also carriesdelete_scheduled_at. showis 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 answers422resize_not_supported, and the password, domain and session endpoints answer404account_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 |
hostingormail_only. A mail-only account has anullpackage.codeand0disk figures. Omitted onprovisioningandunavailablerows - primary_domain: String |
nullwhen 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,LorXL, but not limited to those: other codes appear here verbatim.nullwhen the account has no package - key: String |
mini,basic,pro,max;nullfor a package not in the current catalogue - label: String | e.g.
Pro; falls back to the raw code
- code: String | the current package code, uppercased. Commonly
- local_package: String | package code. Present only while a create or resize is still taking effect, when
packagehas 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 |
nullunless the account is scheduled for deletion - subscription: Object |
nullwhen 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 fromX-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
- cpanel_account: Object | see List cPanel Accounts
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 fromX-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) |
monthlyorannual; 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
- authorization: String | full Authorization header value. Example:
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,processingorchecked_out; while you are polling it can also becomeawaiting_provisioning(payment captured, provisioning parked) orexpired(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_transferorfailedon a bank-transfer order;on_next_invoiceon a post-pay order — see Payment lanes - method_type: String | the resolved payment-method type. Commonly
cardorsepa_debit, but other types can appear —us_bank_account,bacs_debit,acss_debit,au_becs_debit,customer_balance,idealand others are all possible.nulluntil it can be resolved - hosted_invoice_url: String |
null
- status: String |
- 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 fromX-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|packageis not a known package key or package codeinvalid_term|termis notmonthlyorannualproduct_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 chargeinvalid_domain|domainis not a valid domain namebilling_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 termdomain_not_registered|domainis not registered anywheredomain_in_use|domainis already live on another hosting accountdomain_dns_zone_exists| the DNS zone fordomainbelongs to a workspace outside your billing family. Nothing is chargedcart_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, ordomaincould 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 fromX-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 carriesdelete_scheduled_at) - 403
account_suspended| suspended by staff; contact support - 402
service_suspended| suspended for an unpaid invoice
Validation (400):
unknown_package|packageis not a known package key or package codeproduct_unavailable| the target package is not on this billing planno_default_payment_method| a saved default payment method is required to charge the proration off-session, and none was foundbilling_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 cancellationsame_package| already on that packageusage_exceeds_package| the target package is smaller than current disk / mailbox / add-on-domain usageno_price_for_plan| no price for the target package on the subscription's termno_billing_subscription| the account has no billing subscription to prorate against; contact supportsubscription_not_proratable| the cart could not be staged as a proration; refused rather than charged as a brand-new purchasecart_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 fromX-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 fromX-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 fromX-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| nopasswordsupplied - 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;
nullif it reports none - domain_type: String |
parked,subdomainoraddon;nullfor 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.nullwhen it could not be read
- usage: Object | per-kind counters and the package's caps
- addon: Object
- count: Integer
- limit: Integer | the numeric cap;
nullwhen unlimited or unknown - unlimited: Boolean |
trueonly when the server actually said unlimited - at_limit: Boolean |
trueonly against a real numeric cap, so an unknown limit never blocks
- alias: Object | same shape as
addon - subdomain: Object | same shape as
addon
- addon: Object
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 fromX-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,subdomainoraddon - domain: String (required for
parkedandaddon) | 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,
subdomainandaddon) | document root - connect_method: String (optional,
parkedandaddon) | how the domain's DNS is connected:zone,nameserversora_record; see below - seed_dns: Boolean (optional, legacy) |
falseis the same asconnect_method: "a_record". Ignored whenconnect_methodis given - mail: Boolean (optional,
parkedandaddon; defaultfalse) | 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 answersconflicts_found - approved_conflicts:
Array<String>(optional, withreplace_records) | therecord_guidvalues from aconflicts_foundanswer that may be replaced. Any other collision answersconflicts_foundagain
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:
zonewrites the records into this workspace's existing DNS zone for the domain.nameserversmeans 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_recordmeans 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 fromX-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_typeis not one of the three - 422
domain_blank| nodomainsupplied - 422
invalid_hostname|domainis not a valid hostname - 422
label_blank| nolabelsupplied for a subdomain - 422
invalid_label|labelis not a valid DNS label - 422
rootdomain_blank| norootdomainsupplied 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 addsholder_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_methodis notzone,nameserversora_record, ornameserverswas given for a name under a registrable domain - 422
conflicts_found| existing DNS records collide with the records the domain needs; the body addsconflicts. 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 asmailorssl) are refused withinvalid_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 fromX-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 fromX-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 fromX-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.