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

> Turn Release mode on or off, change shared paths and roll back a release with the xCloud Public API (/sites/{uuid}/release-mode) or an AI agent connected to xCloud 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](/docs/zero-downtime-deploys-with-release-mode-in-xcloud/).

## Before you start

- An API token or MCP connection. See [How to access the xCloud API](/docs/how-to-access-the-xcloud-api/) and [How to connect xCloud MCP to your AI agent](/docs/how-to-connect-xcloud-mcp-to-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

```bash
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

```bash
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](/docs/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.

```bash
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](/docs/shared-files-and-folders-in-release-mode/).

## Roll back

Take a `release` from the `releases` list and send it:

```bash
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](/docs/roll-back-a-deployment-in-xcloud/).

## 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](/docs/deploy-git-projects-with-xcloud-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)](/docs/zero-downtime-deploys-with-release-mode-in-xcloud/)
- [Multi-team API tokens and MCP access](/docs/multi-team-api-tokens-and-mcp-access/)
- [xCloud API reference](/docs/xcloud-api/)

If you run into any issues with Release mode through the API or MCP, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/).