xCloud API Documentations

The xCloud Public API is a self-service REST API for all xCloud customers. Use it to programmatically manage your servers, sites, databases, backups, cron jobs, billing, and addons, directly from your own scripts, CI/CD pipelines, or integrations.

📖 Open the interactive API reference →

The reference documents every endpoint with request and response examples, and lets you try calls against your own account. All requests go to one base URL:

https://app.xcloud.host/api/v1

The same contract is available in machine-readable form at https://app.xcloud.host/api/v1/openapi.json and https://app.xcloud.host/api/v1/openapi.yaml, so you can generate a client or check exactly which endpoints exist today.

Authentication

Every request (except the public health check) needs a personal access token sent as a bearer token in the Authorization header:

Authorization: Bearer <your-token>
Accept: application/json

Create a token from your dashboard and scope it to exactly what your integration needs. See How to Access the xCloud API for the step-by-step guide, and Multi-Team API Tokens and MCP Access if one token should work across several teams.

Scope	What it allows
read:servers / write:servers	View servers, databases, cron jobs, PHP versions and monitoring / manage them, and create sites
read:sites / write:sites	View sites, backups, SSL, domains and deployments / manage them. Creating a site needs write:servers.
read:billing	View your plan, invoices, bills, packages, payment methods and subscriptions
read:addons / write:addons	View purchased mailboxes and Mail Delivery / purchase them, verify DNS and read sending credentials
read:tokens	List your API tokens in the current team (names, abilities, teams and timestamps, never the token secrets)
write:tokens	Revoke one of your API tokens in the current team, including the calling token
commands:run	Run one-off commands on a site and read their results
read:email-logs	Read and export Mail Delivery email logs
mcp:invoke	Let an AI agent use this token over MCP
* (Full Access)	Every endpoint except site commands, which need commands:run named on the token

read:tokens and write:tokens are opt-in: no other scope includes them, only Full Access does, and write:tokens does not include read:tokens. No endpoint creates a token or changes its abilities; you do that from the dashboard.

What you can manage

The API grows with almost every xCloud release, so this page does not quote a fixed endpoint count. The interactive reference always lists the current set, grouped as:

Area	What it covers
Fleet overview	Every server and site you can access in one call, with status counts and usage warnings
Servers	Creating and connecting servers, provisioning progress, databases and database users, cron jobs, firewall rules and Fail2Ban, PHP versions, extensions and php.ini, Node.js versions, services, security patches, monitoring, logs, reboots, sudo users and Git deploy keys
Sites	Site details and status, clones and staging sites, domains and DNS checks, SSL, backups (including Docker backups), cron jobs, redirects, PHP version and PHP-FPM/OPcache settings, bulk PHP switching, Git deployments, cache purge, SSH/SFTP config and BetterShield
WordPress	WordPress site creation, plugin and theme lists and actions, updates, WP-Cron, search engine indexing, WP_DEBUG and magic login
Security & health	Vulnerability findings, a team-wide vulnerability rollup and each site’s scan setting, broken-link scans, PageSpeed reports, SSL certificates and the health check
One-click apps & blueprints	The One Click app catalog, compatibility checks, installs and lifecycle actions, and blueprints
Catalog	The app catalog, hosting pricing and the WordPress versions site creation accepts
Alerts	Incident alerts, their read state and push notification settings
Billing & payments	Plans, invoices, bills, packages, payment methods, subscriptions and invoice payment
Addons	Mailbox and Mail Delivery addons, DNS verification and mail client settings
Account	Current user, granted teams, API token listing and revocation, and Cloudflare and Git integrations

To read every server and site in one call, see Get a Fleet Overview with the xCloud Public API and MCP. To deploy a repository, see Deploy Git Projects with the xCloud Public API and MCP.

Recent additions

• Site commands. POST /sites/{site}/commands runs a one-off command as the site’s user, and GET /sites/{site}/commands/{task} returns its status, exit code and output. It needs a token with the opt-in commands:run permission and two-factor authentication. See How to Run and Track Site Commands with the xCloud Public API.
• Bulk page cache purge. POST /sites/bulk/cache-purge purges the WordPress page cache on 1 to 100 sites in one request, with a dry run first. Poll GET /sites/bulk-operations/{bulkOperation} for each site’s result. See How to Purge Page Cache on Many Sites at Once with the xCloud Public API and MCP.
• WordPress database cleanup. POST /sites/{uuid}/database/cleanup/preview previews a cleanup, POST /sites/{uuid}/database/cleanup runs it and GET /sites/{uuid}/database/cleanup/history lists the runs. See How to Clean Up and Optimize Your WordPress Database in xCloud.
• Bulk PHP switching. POST /sites/bulk/php-version previews or queues a PHP version switch for 1 to 100 sites in one request, and xCloud runs the switches one after another on each server. Poll GET /sites/bulk-operations/{bulkOperation} for each site’s result. This is available through the API and MCP only; the dashboard has no bulk PHP switch.
• Site redirects. POST /sites/{uuid}/redirections creates a redirect; PUT and DELETE /sites/{uuid}/redirections/{redirection} update and delete one, with the same access rules as the dashboard.
• Vulnerability scan setting. PUT /sites/{uuid}/vulnerability-scan/settings turns a site’s vulnerability scanning on or off.
• WordPress versions you can install. GET /catalog/wordpress-versions lists the versions that WordPress site creation accepts.
• Stricter filters. List filters such as server status, site status and site type now reject unknown values with 422 instead of ignoring them.

Using the API through MCP

The xCloud MCP server works from this same contract: it never exposes an operation that is not in the API reference, so new endpoints reach AI agents connected over MCP at the same time. See How to Connect xCloud MCP to an AI Agent to set it up.

A first request

List your servers:

curl https://app.xcloud.host/api/v1/servers \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Every response uses a consistent envelope: success, message, and a data payload (with meta pagination on list endpoints). Async operations such as reboots and backups return 202 Accepted and run in the background.

Frequently asked questions

Where is the xCloud API documentation?

The full interactive reference lives at app.xcloud.host/api/v1/docs. It documents every endpoint with request and response examples you can try against your own account.

How many endpoints does the xCloud API have?

The number grows with almost every release, so this page does not list a fixed count. The interactive reference always shows the current set, and you can count the operations yourself in the machine-readable copy at app.xcloud.host/api/v1/openapi.json.

How do I authenticate with the xCloud API?

Every request except the health check needs a personal access token sent as a bearer token in the Authorization header. You can create one from your xCloud dashboard and choose the scopes it should have.

What are the xCloud API rate limits?

Authenticated requests are limited to 60 per minute and unauthenticated requests to 10 per minute. Every response carries rate limit headers, and exceeding the limit returns a 429 with a Retry-After header.

If you face any issues, please do not hesitate to contact our support team.