Sites
OAuth scopes: reads require sites:read, writes require sites:write. Two exceptions:
- The backup export endpoints require
sites:write, including the status read. - The metrics endpoints are POSTs but require only
sites:read. They also require site edit permission; a read-only collaborator gets403{"errors":["Not Authorized"]}.
Site states that change what the endpoints return:
- Dunning-suspended: show, update, delete and tool endpoints return
402service_suspended. List endpoints showdunning_suspended: trueinstead. Theinvoiceobject carriesnumberandhosted_url;hosted_urlisnullwhile a payment is processing. - Server under maintenance or offline: operations that need the server return
409node_maintenanceornode_offline. See Node status. - Pending delete: a deleted site awaiting purge returns
403pending_deleteon update, delete and every nested site endpoint, reads included. It still appears in list results and onGET /api/sites/:id. See Delete a Site.
Related site tooling lives on its own pages: CDN, Cache & Logs and Shield.
List Sites
If you omit the account ID header in this api call, it will return all sites available to your user. If you include the account ID header, it will only return sites for this account.
GET /api/sites
Deleted sites still appear here
A deleted site stays in this list with pending_delete: true until it is purged. To list live sites only, filter on pending_delete.
Returned Params
- sites: Array
- id: String
- name: String
- primary_domain: String
- location: String (Geographic Region)
- account: Object
- id: String
- name: String
- package: String
- dunning_suspended: Boolean
- pending_delete: Boolean |
truewhile the site is awaiting purge - delete_scheduled_at: DateTime | purge date;
nullfor live sites - node_status: Object | the state of the site's region. View Site gives the per-site value. See Node status
- created_at
- updated_at
View Site
GET /api/sites/:id
A pending-delete site still resolves here (no 404) but returns a reduced payload (second block below).
Returned Params
- site: Object
- id: String
- name: String
- primary_domain: String
- location: String (Geographic Region)
- region: String (Availability Zone)
- package: String
- pending_delete: Boolean |
falsehere - php_version: String
- domain_cname: String
- sftp_base_path: String
- dunning_suspended: Boolean | always
falseon this endpoint — a suspended site returns402instead - node_status: Object | the live state of the servers hosting this site. Absent on a pending-delete site. See Node status
- ssh: Object | empty (
{}) unlessssh_statusisavailable- ipaddr: String
- username: String
- password: String
- port: Integer
- ssh_status: String |
available,unavailable(temporary — retry) ornone(no SSH/SFTP access) - domains: Array
- See domains api endpoint
- subscription: Object
- id: String
- status: String
- created_at: DateTime
- updated_at: DateTime
- price: Object
- amount_cents: Integer
- term: String
- run_rate: Object | the subscription's recurring charge, serialized as a money object with a
cents(Integer) key and acurrency_iso(String) key taken from the account's billing plan. It is not a bare integer - sites: Array | every site on this subscription, each a full site summary object (the same shape as an entry in List Sites, without
node_status) — including the site you requested. A shared subscription makes this a large nested payload - product: Object
- id: String
- name: String
- account: Object
- id: String
- name: String
- created_at
- updated_at
Returned Params (pending-delete site)
The response carries only identity plus delete status. region, php_version,
domain_cname, sftp_base_path, dunning_suspended, node_status, ssh,
ssh_status, domains and subscription are omitted.
- site: Object
- id: String
- name: String
- primary_domain: String
- location: String (Geographic Region)
- package: String
- pending_delete: Boolean |
true - status: String |
"pending_delete"(this field is absent for live sites) - delete_scheduled_at: DateTime | when the site will be permanently purged
- account: Object
- id: String
- name: String
- created_at
- updated_at
Node status and refused operations
node_status tells you whether the servers behind a site are healthy. It has the same shape in a GET response and in a 409 refusal.
node_status object
- state: String |
online,maintenanceoroffline - since: DateTime | when the state began;
nullwhen not known - planned: Boolean |
truefor planned maintenance - message: String | plain-text operator notice, or
null. Escape it before rendering - operations: Object | per operation, what happens in this state.
power:available,deferredorrefused.backup,restore,export,scaleandbastion_password_reset:availableorrefused.config_changes:availableordeferred
While a site's server is under maintenance or offline, the endpoints below
return 409 with code node_maintenance or node_offline:
{"errors": ["..."], "code": "node_maintenance", "node_status": {...}}. Nothing is changed; retry once node_status.state is online.
- Create a backup and Delete a backup
- Restore a backup
- Request a backup export (not the status read)
- Restart a Site — only when offline; during maintenance the restart is queued
- Site SSO, both endpoints
- Regenerate SSH credentials
- The WordPress cache-layer endpoints on CDN, Cache & Logs: reading the cache status, and enabling, disabling or purging any layer except
bunny
If the state changes after a request is accepted (202), its task ends CANCELLED with the reason.
Update Site / Resize
PATCH /api/sites/:id
Handles two intents:
- Rename (synchronous) — pass
name. Returns202with an empty body. - Plan change (async) — pass
plan(a Product short_name). The response is the shared cart envelope (see Orders / Carts); poll the cart for completion. It does not return atask_id. The account must have a single site and, for a card-paying workspace, a default payment method on file. The billing term is preserved.paymentandbillingin the response say how the change is paid (see Checkout lanes).
A plan change needs billing permission on the site's workspace. Without it the response is 403 not_authorized and nothing changes, not even name. A rename alone needs only edit permission.
When both fields are present, the rename runs first. If the rename fails validation, the response is 422 and the plan change is skipped.
A pending-delete site cannot be updated: the request returns 403 pending_delete with delete_scheduled_at, and nothing changes.
Params
- name: String | site rename
- plan: String | Product short_name (e.g. "basic")
Returned Params (plan-change path, 202 Accepted)
- status: String |
"accepted" - cart: Object | { token, status, rollup_status, poll_url }
- payment: Object | { status, method_type, hosted_invoice_url }. When the resize is paid by bank transfer,
statusisawaiting_bank_transferand the object addsmethod,invoice_id,invoice_number,amount_due_cents,currency,due_dateandinstructions - orders: Array |
[{ id, status, poll_url }](empty during the async window) - billing: Object | post-pay resizes only:
{ mode: "postpay", invoice_date, entries }
Errors (plan change)
- 400
unknown_product|plandoesn't match any Product short_name - 400
product_unavailable| Product exists but not offered on the account's billing plan - 400
no_default_payment_method| billing account not ready to charge - 403
not_authorized| the user lacks billing permission on the site's workspace - 422
no_price_for_plan| no price matching the account's term - 422
multi_site_resize_unsupported| account has more than one active site - 422
subscription_not_proratable| this subscription cannot be resized; contact support - 422
cart_pay_failed| the payment could not be started - 422
billing_settling| the site's billing is still settling (a freshly created site); also returned by Delete a Site. This is not dunning suspension, which is402service_suspended - Checkout refusals, as on orders:
400billing_details_incomplete;403billing_permission_required;409bank_transfer_in_progress,bank_transfer_busy,postpay_busy;422outstanding_balance_exceeded,in_flight_limit_exceeded,payer_in_dunning,recent_dispute,instant_payment_method_required,sepa_not_trusted,bank_transfer_refused,bank_transfer_failed,postpay_route_changed,postpay_pay_open_invoices,postpay_contact_support,postpay_payment_in_progress,postpay_add_payment_method,postpay_change_refused,postpay_failed. See Orders for each
Restart a Site
Restarts the WordPress container for a site. Other containers, such as the database, are not affected. Returns 202.
During maintenance the restart is queued until maintenance ends (its task shows PAUSED), and the 202 has a body: {"deferred": true, "code": "node_maintenance", "node_status": {...}}. While the server is offline it returns 409 node_offline and nothing is queued.
POST /api/sites/:id/restart
curl -X POST -H "Authorization: Bearer $CLOUDPRESS_TOKEN" -H "X-Auth-Account: $ACCOUNT_ID" \
https://your-instance/api/sites/$SITE_ID/restart
Delete a Site
DELETE /api/sites/:id
Deletes the site, asynchronously. Returns 200 as soon as the request is accepted.
The site then enters a pending-delete state for a retention period (7 days by default). During it:
- The site is powered off; its data and backups are kept.
- Billing is canceled immediately: renewals stop and unused time is credited to the account's balance.
- Transactional Email for the site is suspended.
- The site stays listed in
GET /api/siteswithpending_delete: true, andGET /api/sites/:idreturns the reduced payload withstatus: "pending_delete". - Everything else is locked.
PATCH /api/sites/:id, a secondDELETEand every nested site endpoint, reads included, return403pending_deletewith the site'sdelete_scheduled_at. - Its hostnames stay reserved, so attaching one to a different site in the same billing family returns
422hostname_in_use.
delete_scheduled_at shows when the site is purged. At that point the site, its data and its domains are permanently removed.
Deleting a site requires a user who is a member of the site's account with the billing-management role (an account admin, or a role with both billing and edit permission). For an account that inherits billing, the role is checked on its billing account. Other callers get 403 {"errors":["Not Authorized"]}.
Restoring a pending-delete site and purging it early are not available over the API. Both are on the site's page in the CloudPress dashboard. Restoring is a paid re-purchase of the same plan.
Errors
- 403 | caller is not an account member with the billing-management role (
{"errors":["Not Authorized"]}) - 403
pending_delete| the site is already pending deletion; body includesdelete_scheduled_at - 402
service_suspended| the site is dunning-suspended (see the page header) - 422
billing_settling| the site's billing is still settling (a freshly created site's initial billing window)
Removing a site may affect volume discounts on your other sites.
Site SSO
Single sign-on into a site's WordPress admin or its database (phpMyAdmin).
Not available via OAuth — SSO requires a session or API-key credential.
Without the wp_login role flag, you can only generate URLs for WordPress
users the token's user is explicitly linked to; with wp_login, any user.
List All WP Users
This returns raw user details from the WordPress site. The associated ID is WordPress' internal ID, not a CloudPress user.
GET /api/sites/:id/sso
Returned Params
- users: Array
- ID: Integer
- user_login: String
- display_name: String
- user_email: String
- user_registered: DateTime
- roles: String
- url: String
Login as User
POST /api/sites/:id/sso
Success returns 200 { "url": "..." }; failure returns 400. Returns 422
{"errors":["Missing username"]} when username is required but blank.
Returns 409 node_maintenance or node_offline while the site's server is
not online (the same applies to List All WP Users); see
Node status.
Params
- kind: String |
wordpress(default) ordatabase - username: String | required unless
kindisdatabase. Omittingkindalso requires a username
Returned Params
- url: String
Regenerate SSH credentials
POST /api/sites/{site-id}/ssh/regenerate
Sets a new SSH/SFTP password; host, port, username and host keys stay the same,
and open sessions are dropped. No body; needs sites:write and edit permission.
Returns 202 with {"task": {...}} (shape as in
View a single site task). Poll until status is OK
or FAILED, then read the new password from View Site — this
endpoint never returns it.
Errors
- 402
service_suspended| the site is suspended for an unpaid invoice - 403
pending_delete| the site is pending deletion and locked - 403 (no code) | the credential's user has no edit permission on the site
- 409
ssh_regeneration_in_progress| a regeneration is already running;taskis that one - 409
node_maintenance,node_offline| the site's server is not online; retry later. See Node status - 422
not_provisioned| the site has no SSH access to rotate - 422
ssh_regeneration_refused| the rotation was refused; nothing changed - 429
rate_limited| regenerated within the last 5 minutes; waitretry_afterseconds (also in theRetry-Afterheader) - 503
computestacks_unavailable| temporary outage; nothing changed, retry
Tasks
List all tasks for a given site.
GET /api/sites/{site-id}/tasks
GET /api/sites/{site-id}/tasks/{filter-name}/filter
Filter is optional, can be one of:
- OK
- PENDING
- RUNNING
- CANCELLED
- PAUSED
- FAILED
- TODAY <-- Special filter to show all events from today.
All responses will be limited to the 100 most recent tasks.
Returned Params
Returns an array of objects:
id: Integername: Stringdata: String | Raw data from the eventlabels: Object | A restart deferred by maintenance carriesdeferred: "node_maintenance"; a request refused by the server carriesnode_refusedwith the codestatus: String | OK, PENDING, RUNNING, CANCELLED, PAUSED, FAILEDstart_on: Timestamp | When the task was started. Omitted entirely (notnull) when unsetend_on: Timestamp | Omitted entirely (notnull) when unsetcreated_at: Timestampupdated_at: Timestampperformed_by: Object | Omitted entirely when no user is attributedid: String | null | The user's ID, ornullwhen the actor is maskedname: String | Full name of the user, or a masked stand-inemail: String | null |nullwhen the actor is masked
performed_by is masked for non-customer actors
Tasks performed by the platform itself report
{"id": null, "name": "System", "email": null}, and tasks performed by
support staff report {"id": null, "name": "Support", "email": null}. Only
actions taken by a user in your own workspace return a real ID, name and
email address. Treat name as a display string, not an identifier — match on
id and expect it to be null.
View a single site task
GET /api/sites/{site-id}/tasks/{id}
Returns a single task object (same fields as above).
Errors
- 404
unknown_task| no task with that id belongs to this site
Metrics
Realtime Resources
This endpoint will return the realtime status for a site.
GET /api/sites/{site-id}/metrics/resources
Returned Params
total_storage: Decimal{Image Name}: Object | i.e. "WordPress"cpu: Decimal | Percentage of total planstorage: Decimal | GBmemory: Decimal | MB
Raw Metrics
Returns raw container metrics for a site.
POST /api/sites/{site-id}/metrics/resources
kind can be one or more of:
- cpu
- cpu_throttled
- memory
- memory_throttled
- storage
Params
kind: Array |['storage', 'memory'](example)period_start: Integer | unix timestamp (must be within the last month)period_end: Integer | unix timestamp (after period_start, within the last month)step: String | defaults to '1m'.
Period and Step parameters have no affect on storage metric. That will always return the current value.
Returned Params
service_name: Objectid: Integername: Stringimage: Stringresources: Object | Dependent on which values selectedcpu:Array<time, value>cpu_throttled:Array<time, value>memory:Array<time, value>memory_throttled:Array<time, value>storage: Decimal
Errors
All error bodies use the {"errors": [...]} array shape.
- 422 | empty or invalid
kind, orperiod_start/period_endoutside the last month / out of order - 502 | upstream metric service unavailable
- 400 | unexpected failure
CDN Metrics
Returns raw CDN statistics for a site.
POST /api/sites/{site-id}/metrics/cdn
Params
period_start: Integer | Unix timestamp. Takes precedence overperiod. (>3 months old → 422)step: String | hourly or monthly. Only consulted withperiod_start.period: String | preset window — one of12h,24h,7d,30d. Used only whenperiod_startis absent. Unknown values → 422.
Returned Params
TotalBandwidthUsed: Integer | For the given periodTotalOriginTraffic: Integer | For the given periodTotalRequestsServed: Integer | For the given periodCacheHitRate: IntegerOriginResponseTimeChart: Object |"2025-11-20T00:00:00Z": 0(ISO8601 timestamp → Integer)BandwidthUsedChart: ObjectBandwidthCachedChart: ObjectCacheHitRateChart: ObjectRequestsServedChart: ObjectPullRequestsPulledChart: ObjectOriginTrafficChart: ObjectGeoTrafficDistribution: Object | e.g."EU: Stockholm, SE": 0Error3xxChart: ObjectError4xxChart: ObjectError5xxChart: Object
The response can include additional fields beyond those listed.
Units: bandwidth and traffic totals are in bytes. CacheHitRate is a percentage from 0 to 100, unrounded.
Errors
- 409 | CDN not active for this site
- 422 | missing/zero/too-old
period_start, or unknownperiod - 502 | upstream statistics fetch failed
Example: Show Monthly Bandwidth
curl -X POST -d '{"period_start": 1760983782, "step": "monthly"}'
This will return data for the past month, in daily increments, but more importantly, the TotalBandwidthUsed value will be for the entire 30 day period.
See also Shield metrics.
Backups
Please use the Tasks endpoint to monitor the status of these actions.
List All Backups
Return a list of backups for a given site, grouped by volume. Returns [] when
there are no volumes; a volume with no archives renders as {}.
GET /api/sites/{site-id}/backups
Returned Params
{label}: Object | i.e. wordpress, or mysqlid: Integer | ID of the volume (required for backup operations)size: Decimal | GB - total raw backup size (not the volume's provisioned capacity)usage: Decimal | GB - compressed and deduplicated backup size (actual usage on disk)archives: Arrayid: Stringname: Stringcreated: String | in iso8601 format
Create a backup
PATCH /api/sites/{site-id}/backups/{volume-id}
Returns 202. An unknown volume returns 404 {"errors":["Volume not found"]}.
Returns 409 node_maintenance or node_offline while the site's server refuses
backups; see Node status.
Params
name: String | Backup Name
Delete a backup
DELETE /api/sites/{site-id}/backups/{volume-id}
Returns 202. Returns 409 node_maintenance or node_offline while the
site's server refuses backups.
Params
backup_id: String | Backup ID
Restore a backup
PATCH /api/sites/{site-id}/restores/{volume-id}
Returns 202. Returns 409 node_maintenance or node_offline while the
site's server refuses restores; see Node status.
Params
backup_id: String | Backup ID
Request a backup export
POST /api/sites/{site-id}/backups/{volume-id}/export
Requests a downloadable .tar.gz of one backup archive. Asynchronous: returns 202 with {"status": "preparing", "backup_id": "..."}. Poll Export status for the download URL.
Both export endpoints require sites:write and edit permission on the site, including the status read.
Params
backup_id: String (required) | Archive ID from List All Backups
Errors
- 422 |
backup_idmissing ({"errors":["backup_id is required"]}) - 404 | unknown volume (
{"errors":["Volume not found"]}) - 403 | the token's user has no edit permission on the site (
{"errors":["Not Authorized"]}) - 409
node_maintenance,node_offline| the site's server refuses exports. See Node status
If an export is already running for the volume, the request has no effect. Use the status endpoint to follow progress.
Export status and download
GET /api/sites/{site-id}/backups/{volume-id}/export?backup_id={archive-id}
Returns the export state of a single archive, plus the download URL once it is ready. Fetch the URL with a plain HTTPS GET; it needs no CloudPress credentials.
Params
backup_id: String (required) | Archive ID, passed in the query string
Returned Params
status: String | one ofnone,in_progress,ready,expired,failedurl: String | only whenready— HTTPS URL to the.tar.gzexpires_at: String | only whenready— iso8601, when the URL lapsessize: Integer | only whenready— size of the export in byteserror: String | only whenfailed— human-readable failure reason
Errors
- 422 |
backup_idmissing ({"errors":["backup_id is required"]}) - 404 | unknown volume (
{"errors":["Volume not found"]}), or no archive matchesbackup_id({"errors":["Backup not found"]}) - 403 | the token's user has no edit permission on the site (
{"errors":["Not Authorized"]})
Treat url as a bearer secret
Anyone who has it can download the entire backup until it expires. Don't log, forward or store it. Once status is expired, request a fresh export.
Change PHP Version
List Available
GET /api/sites/{site-id}/variants
Returned Params
php:Array<Object>| Currently onlyphpis returned.id: Integer |variant_idneeded for changing the versionlabel: Stringis_default: Boolean | When deploying a new site, this will be used.active: Boolean | Current version the site is using
Change
When changing a site's php version, the site will be restarted with a different container image. Please allow time for the site to restart. Returns 202. The URL segment must be php — any other variant returns 422 {"errors":["only php version changes are allowed"]}.
PATCH /api/sites/{site-id}/variants/php
Params
variant_id: Integer
Returned Params (202 Accepted)
task_id: Integer | The ID of the task so you can follow along.