# How to Manage Backups with the xCloud Public API and MCP

> Connect backup storage, set a site's backup schedule, take a backup and restore it in place or into another site with the xCloud Public API or an AI agent over MCP.

You can run a site's backups from a script or an AI agent: connect backup storage, choose where and how often a site backs up, take a backup now, and restore one in place or into another site. Each action is a [Public API](/docs/xcloud-api/) endpoint, and the same actions are tools in any AI agent connected to [xCloud MCP](/docs/how-to-connect-xcloud-mcp-to-ai-agent/).

Restores and removing storage start with a dry run that shows exactly what will change. Over MCP, every action that overwrites or removes something waits for your OK.

## What you can do

| Task | Public API | MCP operation | Token permission |
|---|---|---|---|
| List backup storage | `GET /storage-providers` | `storage-providers.index` | `read:servers` |
| Connect storage | `POST /storage-providers` | `storage-providers.store` | `write:servers` |
| Edit storage | `PUT /storage-providers/{uuid}` | `storage-providers.update` | `write:servers` |
| Test a connection | `POST /storage-providers/{uuid}/check-connection` | `storage-providers.checkConnection` | `write:servers` |
| Remove storage | `DELETE /storage-providers/{uuid}` | `storage-providers.destroy` | `write:servers` |
| Read a site's backup settings | `GET /sites/{uuid}/backup-settings` | `sites.backupSettings` | `read:sites` |
| Change a site's backup settings | `PUT /sites/{uuid}/backup-settings` | `sites.backupSettings.update` | `write:sites` |
| Remove a backup destination | `DELETE /sites/{uuid}/backup-settings/{uuid}` | `sites.backupSettings.destroy` | `write:sites` |
| Take a backup now | `POST /sites/{uuid}/backup` | `sites.backup` | `write:sites` |
| List backups | `GET /sites/{uuid}/backups` | `sites.backups` | `read:sites` |
| Restore in place | `POST /sites/{uuid}/backups/{uuid}/restore` | `sites.backups.restore` | `write:sites` |
| Restore into another site | `POST /sites/{uuid}/backups/{uuid}/restore-to-site` | `sites.backups.restore-to-site` | `write:sites` |

In MCP, the tool name is the operation name with dots replaced by underscores, for example `sites_backups_restore`.

All paths start with `https://app.xcloud.host/api/v1`. These are for regular sites. Docker apps have their own backup endpoints; see [Back Up and Restore Docker Apps](/docs/backup-and-restore-docker-apps/).

## Prerequisites

- A paid plan. Backups are not available on the free plan, and backup storage cannot be connected on a trial plan.
- An xCloud API token with the permissions in the table above. See [How to Access the xCloud API](/docs/how-to-access-the-xcloud-api/).
- A team role that may add, edit or remove storage providers (for storage), and change the site's settings (for backups and restores).
- For MCP, an AI agent connected to xCloud MCP. See [How to Connect xCloud MCP to Your AI Agent](/docs/how-to-connect-xcloud-mcp-to-ai-agent/).
- The site's UUID. `GET /api/v1/sites` lists them.

## Step 1: Connect backup storage

Send the storage kind in `provider` and its sign-in details. xCloud tests the connection **before** it saves anything, so a wrong key or bucket is refused with `422` and nothing is created.

```bash
export XCLOUD_TOKEN='YOUR_API_TOKEN'

curl -X POST 'https://app.xcloud.host/api/v1/storage-providers' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "cloudflare_r2",
    "access_key_id": "YOUR_ACCESS_KEY_ID",
    "secret_key": "YOUR_SECRET_KEY",
    "region": "auto",
    "bucket": "docs-demo-backups",
    "endpoint": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com"
  }'
```

**Expected result:** a `201` response with the message "Storage provider connected. The connection test passed." Save the storage `uuid` for the next step.

| `provider` | What to send |
|---|---|
| `digital_ocean`, `vultr`, `cloudflare_r2`, `backblaze_b2`, `hetzner`, `google_cloud_storage`, `wasabi`, `other` (S3-compatible) | `access_key_id`, `secret_key`, `region`, `bucket`, `endpoint` (an https URL). `other` also takes `use_path_style_endpoint`, for MinIO or Ceph |
| `sftp` | `label`, `host`, `port` (default 22), `username`, `password`, `backup_path` (created when missing) |
| `google_drive`, `pcloud` | Nothing more. These need a sign-in in your browser, so the call answers `422` with `browser_step_required` and a `dashboard_url`. Open it and finish the sign-in under **Add New Provider** |

For an Amazon S3 bucket, send `other` with your bucket's AWS region and the S3 endpoint for that region, starting with `https://`.

Your keys and passwords go in once and are never returned. Every read shows only `access_key_id_hint` (masked) and `has_secret`.

To check a saved storage later, call `POST /storage-providers/{uuid}/check-connection`. The answer has `connected` (true or false), and when it fails, a `reason` and a `message` from the storage itself.

To edit a storage, send only the fields that change to `PUT /storage-providers/{uuid}`. Leave the keys out to keep the saved ones. For SFTP, a new host, port or username needs the password again. The kind of a storage cannot change; connect a new one instead.

For step-by-step setup on each provider's side, see [Cloudflare R2](/docs/cloudflare-r2-storage-for-site-backup/), [Amazon S3](/docs/aws-s3-bucket-for-site-backup-in-xcloud/) or [Google Drive](/docs/google-drive-for-site-backup-xcloud/).

## Step 2: Set the site's backup schedule

Read the current settings first. The answer lists the site's backup destinations, the storage you can choose from and how many remote destinations the site may have.

```bash
curl 'https://app.xcloud.host/api/v1/sites/SITE_UUID/backup-settings' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'
```

Then save a destination. This example backs up files and database to the storage from Step 1 every day and keeps 30 days of backups:

```bash
curl -X PUT 'https://app.xcloud.host/api/v1/sites/SITE_UUID/backup-settings' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "storage_provider": "STORAGE_UUID",
    "type": "full",
    "database": true,
    "files": true,
    "auto_backup": true,
    "auto_backup_frequency": "daily",
    "auto_delete": true,
    "delete_after_days": 30
  }'
```

**Expected result:** a `200` response with the message "Backup settings saved" and the saved destination. xCloud then updates the backup schedule on the server.

| Field | Values |
|---|---|
| `type` | `full` or `incremental` |
| `auto_backup_frequency` | `twelve_hours`, `daily`, `weekly` or `monthly` (needed when `auto_backup` is true) |
| `delete_after_days` | 1 to 3650. The newest backup is always kept |
| `is_local` | `true` for backups on the server itself. Leave out `storage_provider` for a local destination |

Sending the same storage again updates that destination. A different storage adds a second remote destination. To move a destination to other storage, send its `backup_setting` UUID with the new `storage_provider`.

To remove a destination, call `DELETE /sites/{uuid}/backup-settings/{uuid}`. Add `"purge_files": true` only if the stored backups should be deleted too. Without it, the backups stay.

## Step 3: Take a backup now and follow it

```bash
curl -X POST 'https://app.xcloud.host/api/v1/sites/SITE_UUID/backup' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "remote" }'
```

**Expected result:** a `200` response with a `task_uuid`. `type` is `local` (default) or `remote`. On a site with several remote destinations, pick one with `backup_setting` or `storage_provider`. If the remote storage is missing or cannot be reached, the request is refused with `422` before anything starts.

Follow the backup with `GET /sites/{uuid}/events/{task_uuid}` until it finishes or fails. Then `GET /sites/{uuid}/backups` lists it with its `uuid`, `date` and `status`. Only a backup with `status: completed` can be restored.

## Step 4: Restore a backup in place

A restore overwrites the site, so always send a dry run first. It runs the checks and restores nothing.

```bash
curl -X POST 'https://app.xcloud.host/api/v1/sites/SITE_UUID/backups/BACKUP_UUID/restore' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ "restore_type": "both", "dry_run": true }'
```

**Expected result:** a `200` response with `would_restore`: the site, the backup's time, destination and files, and `will_overwrite`, which says in plain words what is replaced. For example (inside `data`, list of backup files left out):

```json
{
  "dry_run": true,
  "would_restore": {
    "site": { "uuid": "SITE_UUID", "name": "example.com" },
    "backup": { "taken_at": "2026-11-15 02:00:00", "destination": "cloudflare_r2 docs-demo-backups" },
    "restore_type": "both",
    "restore_method": "replace",
    "will_overwrite": [
      "The files of example.com are replaced by the backup's files (files added since the backup stay).",
      "The database example_db of example.com is replaced by the backup's database: changes since the backup are lost."
    ]
  }
}
```

| Field | Values |
|---|---|
| `restore_type` | `both` (default), `database` or `file` |
| `restore_method` | `replace` (default: newer files stay) or `remove` (every file of the site is deleted first) |

When the preview is right, send the same body without `dry_run`. The answer is `202` with `status: queued`, and the restore runs on the server. Follow it in `GET /sites/{uuid}/events`.

The dry run does not check whether the storage is reachable or every backup file is still there. Those checks run on the real call, and a refusal is a `422` that says why. Nothing is restored in that case.

## Step 5: Restore into another site or a new site

Restore-to-site copies a WordPress backup into a **different** WordPress site in your team. All files and the whole database of the target are replaced. The target keeps its own domain and database credentials, and the source site is not changed.

```bash
curl -X POST 'https://app.xcloud.host/api/v1/sites/SOURCE_SITE_UUID/backups/BACKUP_UUID/restore-to-site' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ "target_site": "TARGET_SITE_UUID", "dry_run": true }'
```

**Expected result:** a `200` response with `would_restore`, naming the source site, the backup and the target site with its server. Send the same body without `dry_run` to start it. The answer is `202`, and the target shows a migration in progress. Follow it with `GET /sites/{target uuid}/status` until the target is provisioned again.

To restore into a **new** site, create a WordPress site first, wait until it is provisioned, then use its UUID as `target_site`. The target's server must be connected and provisioned. To do the same in the dashboard, see [How to Restore a Backup to Another Site](/docs/how-to-restore-a-backup-to-another-site/).

## Manage backups with an AI agent over MCP

In an MCP client connected to xCloud, ask in plain language:

```text
Restore example.com from last night's backup. Show me what will be
overwritten first and wait for my OK.
```

The agent lists the backups with `sites_backups`, picks the one from last night and sends a dry run with `sites_backups_restore`. It shows you the preview: the site, the backup time and what will be overwritten. The real restore is destructive, so xCloud MCP refuses it unless the call carries `confirm: true`, which the agent may only set after you approve. It then follows the restore with `sites_events`.

On the unified (compact) MCP profile, the agent finds the operation with `search` and runs it with `execute`. A restore still needs `confirm: true`.

Other prompts that work:

- "Connect my Cloudflare R2 bucket docs-demo-backups as backup storage and test it."
- "Back up example.com daily to R2 and keep 30 days."
- "Take a backup of example.com now and tell me when it's done."
- "Restore last Monday's backup of example.com into staging.example.com."

Changing backup settings, removing a backup destination and removing storage are destructive too, so they also need your OK before the agent can send `confirm: true`. Removing storage has a dry run that names the sites that lose that destination. Connecting storage, testing a connection and taking a backup run straight away.

For a Google Drive or pCloud storage, the agent gives you the dashboard link to finish the sign-in yourself.

## Troubleshooting

| Response | Cause | Fix |
|---|---|---|
| `401` | No token, or the token was revoked | Send `Authorization: Bearer <token>` with an active token |
| `403` "not available on the free plan" | The team is on the free plan | Upgrade the plan |
| `403` on storage providers | The token lacks `read:servers`/`write:servers`, the team is on a trial, or your role cannot manage storage | Use a token with the right permission, or ask the team owner |
| `404` "Backup not found for this site" | The backup UUID belongs to another site | Take the UUID from `GET /sites/{uuid}/backups` of the same site |
| `422` "The connection test failed" | The keys, bucket, endpoint or SFTP details are wrong | Fix the details and send again. Nothing was saved |
| `422` `browser_step_required` | Google Drive or pCloud | Open `dashboard_url` and finish the sign-in in the browser |
| `422` "Only a completed backup can be restored" | The backup failed or is still running | Pick a backup with `status: completed` |
| `422` "available for WordPress sites only" | Restore-to-site on a site that is not WordPress | Restore the site in place instead |
| `422` "This is a Docker app" | The site is a Docker app | Use the [Docker app backup](/docs/backup-and-restore-docker-apps/) endpoints |

## Frequently asked questions

### Can my AI agent restore a backup without asking me?

No. xCloud MCP refuses a restore unless the call carries confirm: true, which the agent may only set after you approve. The agent first sends a dry run that shows the site, the backup time and what will be overwritten, and restores nothing.

### Does the API ever return my storage keys or SFTP password?

No. You send the keys or password once, when you connect or edit the storage. Every read shows only a masked hint of the key ID and whether a secret is saved.

### Can I connect Google Drive or pCloud through the API?

Not fully. Both need a sign-in in your browser, which an API token cannot do. The call answers with browser_step_required and a dashboard link. Open the link, finish the sign-in under Add New Provider, and the storage then shows up in the API and MCP like any other.

### Can I restore a backup into a brand new site?

Yes, in two steps. Create a new WordPress site, wait until it is provisioned, then restore the backup into it with restore-to-site. Restoring into another site works for WordPress sites only.

## Next steps

- Read how backups work in the dashboard in [Backups in xCloud](/docs/backups-in-xcloud/).
- See the full request and response format in the [xCloud Public API reference](https://app.xcloud.host/api/v1/docs).
- Work across several teams from one token with [Multi-Team API Tokens and MCP Access](/docs/multi-team-api-tokens-and-mcp-access/).

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