How to Manage Backups with the xCloud Public API and MCP

Updated November 16, 2026 · 10 min read

Summarize with:
Share:

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 endpoint, and the same actions are tools in any AI agent connected to xCloud MCP.

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.

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.
  • 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.
  • 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.

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, Amazon S3 or Google Drive.

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.

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:

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

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.

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):

{
  "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.

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.

Manage backups with an AI agent over MCP

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

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

If you run into any issues with managing backups through the API or MCP, feel free to reach out to our support team for help.