How to Manage Zero-Downtime Deployments (Release Mode) with the xCloud Public API and MCP

Everything the Release mode card does in the dashboard, you can also do from a script or an AI agent. The xCloud Public API has five operations under /sites/{uuid}/release-mode, and xCloud MCP offers the same operations as tools, generated from the same API description, with the same permissions.

For what Release mode does, see How to use zero-downtime deployments.

Before you start

• An API token or MCP connection. See How to access the xCloud API and How to connect xCloud MCP to your AI agent.
• Reading the state needs the read:sites scope. Every change needs the write:sites scope and the site:manage-deploy-scripts permission on the team (Manage deploy scripts in the dashboard).
• The site’s UUID. Requests go to https://app.xcloud.host/api/v1.

The operations

Method and path	What it does	MCP tool
GET /sites/{uuid}/release-mode	Reads whether Release mode is on, why it can’t be turned on, the shared paths, the releases and the last operation.	sites_release-mode_show
POST /sites/{uuid}/release-mode/enable	Turns Release mode on.	sites_release-mode_enable
POST /sites/{uuid}/release-mode/disable	Turns Release mode off. The other releases are removed.	sites_release-mode_disable
PUT /sites/{uuid}/release-mode	Sets the shared paths.	sites_release-mode_update
POST /sites/{uuid}/release-mode/rollback	Rolls back to a kept release.	sites_release-mode_rollback

On the compact MCP profile, the agent calls these by their operation names (sites.release-mode.show and so on): the read through xcloud_execute_read, and enable, disable, update and rollback through xcloud_execute_destructive, because each one changes what a live site serves.

Read the state

curl -s https://app.xcloud.host/api/v1/sites/SITE_UUID/release-mode \
  -H "Authorization: Bearer YOUR_TOKEN"

The data object holds:

• enabled, current_release (the live release, a UTC time like 20261110093117) and previous_release;
• enable_refusal: why Release mode can’t be turned on, or null;
• shared_paths, default_shared_paths and custom_shared_paths;
• admin_installs_off: true for a WordPress site, where plugin and theme installs from the admin are off while Release mode is on;
• keep_releases: how many releases the server keeps (5, or 3 for a container site);
• releases: the last deploy and rollback records, newest first, each with release, commit, result (ok, bad, rollback or converted), duration, deployed_by, at and live;
• last_operation: the last enable, disable, rollback or shared paths change, with action, status (pending, succeeded or failed), release, reason and at.

Turn Release mode on or off

curl -s -X POST https://app.xcloud.host/api/v1/sites/SITE_UUID/release-mode/enable \
  -H "Authorization: Bearer YOUR_TOKEN"

The call answers 202 and the change runs in the background. Poll GET /sites/{uuid}/release-mode until last_operation.status is succeeded or failed. Use /disable the same way to turn it off.

Other answers:

• 422 with the reason when the site can’t use Release mode (the same reasons the card shows, listed in Release mode messages and fixes).
• 409 when Release mode is already in that state, or when a deploy, rollback or switch is running for the site.

Change the shared paths

Send the whole list. Use null to go back to the defaults for the site’s stack.

curl -s -X PUT https://app.xcloud.host/api/v1/sites/SITE_UUID/release-mode \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shared_paths": [".env", "storage", "public/uploads"]}'

It answers 202; poll as above. Release mode must be on. A path that breaks a rule (absolute, .., .git, the web root, a duplicate, a path inside another listed path, a path that doesn’t exist yet, a file tracked by Git, or more than 50 paths) is refused with 422 and the reasons. Container sites share no paths. See Shared files and folders in Release mode.

Roll back

Take a release from the releases list and send it:

curl -s -X POST https://app.xcloud.host/api/v1/sites/SITE_UUID/release-mode/rollback \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"release": "20261110093117"}'

The answer is 202 with a message such as “Rolling back to release 20261110093117. Poll GET /sites/{uuid}/release-mode until last_operation.status is succeeded or failed.” The database, .env and shared files are not changed. If the release was removed from the server or never went live, the rollback fails, last_operation.reason says why, and the live release stays. A rollback without the site:manage-deploy-scripts permission answers 403.

More in How to roll back a deployment.

Create a Git site with Release mode

Add "release_mode": true to POST /servers/{uuid}/sites/git or POST /servers/{uuid}/sites/git/auto. It works for Laravel, custom PHP and Node.js sites on servers that support Release mode, and for members with the site:manage-deploy-scripts permission. The site converts after its first successful deploy. When Release mode is not available, the request answers 422 and creates nothing. See Deploy Git projects with the Public API and MCP.

Ask your AI agent

With xCloud MCP connected, you can ask in plain words, for example:

• “Turn on release mode for acme-shop and tell me when it’s done.”
• “Show the releases of acme-shop and roll back to the one before the live one.”
• “Share public/uploads between releases on acme-shop.”

Frequently asked questions

Why does the rollback call answer 403?

Rollback needs the site:manage-deploy-scripts permission on the team, the same permission as turning Release mode on or off, plus a token with the write:sites scope. A member who may only deploy cannot roll back.

How do I know when an enable, disable or rollback has finished?

Those calls answer 202 and run in the background. Poll GET /sites/{uuid}/release-mode until last_operation.status is succeeded or failed. A failed operation carries the reason in last_operation.reason.

Can I create a Git site with Release mode already chosen?

Yes. Send release_mode set to true on POST /servers/{uuid}/sites/git or /servers/{uuid}/sites/git/auto. The site converts after its first successful deploy. If Release mode is not available for that site type, server or member, the request answers 422 and nothing is created.

Related guides

• How to use zero-downtime deployments (Release mode)
• Multi-team API tokens and MCP access
• xCloud API reference

If you run into any issues with Release mode through the API or MCP, feel free to reach out to our support team.