Skip to content

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 gets 403 {"errors":["Not Authorized"]}.

Site states that change what the endpoints return:

  • Dunning-suspended: show, update, delete and tool endpoints return 402 service_suspended. List endpoints show dunning_suspended: true instead. The invoice object carries number and hosted_url; hosted_url is null while a payment is processing.
  • Server under maintenance or offline: operations that need the server return 409 node_maintenance or node_offline. See Node status.
  • Pending delete: a deleted site awaiting purge returns 403 pending_delete on update, delete and every nested site endpoint, reads included. It still appears in list results and on GET /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 | true while the site is awaiting purge
    • delete_scheduled_at: DateTime | purge date; null for 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 | false here
    • php_version: String
    • domain_cname: String
    • sftp_base_path: String
    • dunning_suspended: Boolean | always false on this endpoint — a suspended site returns 402 instead
    • node_status: Object | the live state of the servers hosting this site. Absent on a pending-delete site. See Node status
    • ssh: Object | empty ({}) unless ssh_status is available
      • ipaddr: String
      • username: String
      • password: String
      • port: Integer
    • ssh_status: String | available, unavailable (temporary — retry) or none (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 a currency_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, maintenance or offline
  • since: DateTime | when the state began; null when not known
  • planned: Boolean | true for 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, deferred or refused. backup, restore, export, scale and bastion_password_reset: available or refused. config_changes: available or deferred

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.

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:

  1. Rename (synchronous) — pass name. Returns 202 with an empty body.
  2. 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 a task_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. payment and billing in 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, status is awaiting_bank_transfer and the object adds method, invoice_id, invoice_number, amount_due_cents, currency, due_date and instructions
  • 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 | plan doesn'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 is 402 service_suspended
  • Checkout refusals, as on orders: 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, 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/sites with pending_delete: true, and GET /api/sites/:id returns the reduced payload with status: "pending_delete".
  • Everything else is locked. PATCH /api/sites/:id, a second DELETE and every nested site endpoint, reads included, return 403 pending_delete with the site's delete_scheduled_at.
  • Its hostnames stay reserved, so attaching one to a different site in the same billing family returns 422 hostname_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 includes delete_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) or database
  • username: String | required unless kind is database. Omitting kind also 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; task is 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; wait retry_after seconds (also in the Retry-After header)
  • 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: Integer
  • name: String
  • data: String | Raw data from the event
  • labels: Object | A restart deferred by maintenance carries deferred: "node_maintenance"; a request refused by the server carries node_refused with the code
  • status: String | OK, PENDING, RUNNING, CANCELLED, PAUSED, FAILED
  • start_on: Timestamp | When the task was started. Omitted entirely (not null) when unset
  • end_on: Timestamp | Omitted entirely (not null) when unset
  • created_at: Timestamp
  • updated_at: Timestamp
  • performed_by: Object | Omitted entirely when no user is attributed
    • id: String | null | The user's ID, or null when the actor is masked
    • name: String | Full name of the user, or a masked stand-in
    • email: String | null | null when 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 plan
    • storage: Decimal | GB
    • memory: 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: Object
    • id: Integer
    • name: String
    • image: String
    • resources: Object | Dependent on which values selected
      • cpu: 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, or period_start/period_end outside 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 over period. (>3 months old → 422)
  • step: String | hourly or monthly. Only consulted with period_start.
  • period: String | preset window — one of 12h, 24h, 7d, 30d. Used only when period_start is absent. Unknown values → 422.
Returned Params
  • TotalBandwidthUsed: Integer | For the given period
  • TotalOriginTraffic: Integer | For the given period
  • TotalRequestsServed: Integer | For the given period
  • CacheHitRate: Integer
  • OriginResponseTimeChart: Object | "2025-11-20T00:00:00Z": 0 (ISO8601 timestamp → Integer)
  • BandwidthUsedChart: Object
  • BandwidthCachedChart: Object
  • CacheHitRateChart: Object
  • RequestsServedChart: Object
  • PullRequestsPulledChart: Object
  • OriginTrafficChart: Object
  • GeoTrafficDistribution: Object | e.g. "EU: Stockholm, SE": 0
  • Error3xxChart: Object
  • Error4xxChart: Object
  • Error5xxChart: 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 unknown period
  • 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 mysql
    • id: 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: Array
      • id: String
      • name: String
      • created: 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
Errors
  • 422 | backup_id missing ({"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 of none, in_progress, ready, expired, failed
  • url: String | only when ready — HTTPS URL to the .tar.gz
  • expires_at: String | only when ready — iso8601, when the URL lapses
  • size: Integer | only when ready — size of the export in bytes
  • error: String | only when failed — human-readable failure reason
Errors
  • 422 | backup_id missing ({"errors":["backup_id is required"]})
  • 404 | unknown volume ({"errors":["Volume not found"]}), or no archive matches backup_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 only php is returned.
    • id: Integer | variant_id needed for changing the version
    • label: String
    • is_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.