API overview

Authentication

All /api/* requests authenticate with an HTTP token in the Authorization header. Both the Token and Bearer schemes are accepted:

Authorization: Token {{ CloudPress API Token }}

Authorization: Bearer {{ CloudPress API Token }}

There are three credential types, all presented the same way. The server resolves which kind it is (session / API key first, then OAuth):

IP Restriction

You may restrict access by IP to a particular API Key in the CloudPress API Key Manager. Note that when you attempt to connect from a non-authorized IP, you will receive the same response as if you supplied an invalid API Key.

By default there is no IP restriction in place.

Setting Account Scope

Some API endpoints require an Account Scope. To specify which account you would like to be working under, include the header X-Auth-Account set to your Account ID:

X-Auth-Account: {{ CloudPress Account ID }}

Behavior:

• For a user API key, X-Auth-Account scopes the request to a single account and sets the account context. Without it, list endpoints return resources across all accounts the key's user can access.
• Two lists ignore the header entirely. GET /api/domains and GET /api/dns_zones always return every domain / zone the key's user can reach, whether or not you send X-Auth-Account. Filter client-side if you need one account's subset.
• Some endpoints require it and return 400 {"errors":["Missing X-Auth-Account"],"code":"missing_account"} when it is absent — Orders, Carts, Subscriptions, Users, SSO, cPanel accounts, and all Domain Registration endpoints. DNS-zone create applies the same rule but renders its own body without a code key — 400 {"errors":["Missing X-Auth-Account"]} — so don't branch on missing_account there. Mailspace create also needs an account context and answers 400 account_required.
• OAuth tokens always carry an account, so the header is ignored for them.

Authentication Failures

A failed authentication returns 401 with the header WWW-Authenticate: Token realm="Application" and an empty body. Causes include no/invalid token, an IP not on the key's access list, a trial account, or an X-Auth-Account value that doesn't match an account the token can access.

{ "error": "invalid_token", "error_description": "token audience is not valid for /api" }

Conventions

• All API routes are under /api/. All responses are JSON.
• Resource IDs are GUIDs, except numeric task IDs, integer volume IDs, integer DNS record-type codes, and numeric domain_contact IDs.
• Timestamps are ISO 8601, UTC.
• Async operations return 202 Accepted — poll a task, registrar process, or cart to check completion (see Async Operations).

Pagination

Pagination is not a site-wide convention. Exactly five index endpoints accept page and per_page:

• GET /api/orders
• GET /api/subscriptions
• GET /api/domains
• GET /api/dns_zones
• GET /api/cpanel_accounts

Every other index action — sites, tasks, users, accounts, API keys, DNS records, domain registrations, domain contacts, Mailspace, a cPanel account's domains, and all site sub-resources — ignores both parameters and returns the full set in a single response.

Rate Limiting

Requests are limited to 600 per 10 minutes, counted per client IP address and per controller — not per credential. Two consequences follow:

• One credential gets a separate 600-request budget against each group of endpoints (sites, domains, DNS zones, orders, …), so spreading work across resources is not capped at a single shared 600.
• Two credentials calling from the same source IP — behind one NAT or egress gateway — share a bucket and can exhaust each other's budget.

Exceeding the limit returns 429 with an empty body.

Error Responses

{
  "errors": ["This site is pending deletion and is locked. Restore it to make changes."],
  "code": "pending_delete",
  "delete_scheduled_at": "2026-09-01T14:22:05Z"
}

Async Operations

Most provisioning operations are asynchronous and return 202 Accepted with a reference to poll.

• Tasks — several operations open a Task, but only some of them hand the id back. Three cases, and the difference matters when you plan your polling:

  • 202 carrying a task_id — PHP version change (PATCH /api/sites/{site-id}/variants/php) and cache enable / disable / purge. Poll the returned id directly.
  • 202 with no task id — restart, backup create and delete, restore, and site-domain promote / remove. A Task is created, but the response body is empty, so locate it with GET /api/sites/{site-id}/tasks instead. Site-domain add does return an id, but it is the new domain's guid, not a task id.
  • No Task at all — account-role removal (DELETE /api/accounts/{account-id}/roles/{id}) and account deletion (DELETE /api/accounts/{account-id}) answer with a bare 202. Nothing is created to poll; re-read the account or its roles to confirm the outcome.

  Poll a task with GET /api/tasks/:id or GET /api/sites/:site_id/tasks/:id. Task statuses: PENDING, RUNNING, OK, FAILED, CANCELLED, PAUSED. - Carts — site creation (POST /api/orders), site resize / plan-change (PATCH /api/sites/:id with plan), and domain orders (POST /api/orders/domain) are polled via the cart, not a task: they return a cart envelope; poll the cart for materialized orders. - Registrar processes — domain-registration mutations may open a process; poll it for completion.

Completion Callback

Order creation accepts an optional callback so you receive a webhook when the async work finishes instead of polling:

{ "callback": { "url": "https://your-app.com/webhook", "authorization": "Bearer your-secret" } }

See Callbacks for the full contract.

About Endpoint

CloudPress offers an 'about' endpoint that provides information about who you are logged in as, as well as information about available resources. It accepts any valid token regardless of OAuth scope.

GET /api/about

curl -H "Authorization: Bearer $CLOUDPRESS_TOKEN" \
  https://your-instance/api/about