> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/platform/how-to/fleets/backups-and-restores/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# Backups and restores

A backup is the safety net for Beam device operations. Take one before a software change or a service removal, and you have a configuration you can roll back to. A backup captures the device’s services, templates, failover groups, server definitions, and local users. Backup and restore operations run asynchronously on the device and return `202 Accepted`.

## Create a backup

A backup is triggered with `POST` against the device. Use a descriptive `backupName`, such as one with a date, so its purpose is clear later.

* Terminal window

```bash
curl -X POST "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/devices/my-device/backup" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "displayName": "Pre-update backup" },
    "spec": {
      "backupName": "pre-update-20260415-100000",
      "backupAssetFile": false
    }
  }'

```

The call returns `202 Accepted` and the backup completes on the device over the next while. Configuration access on the device is blocked while a backup or restore is in progress.

## Browse backups

List the backups in a project, and read one to get its stored file details:

```bash
curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/backups" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/backups/<BACKUP_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

A backup record carries its `timestamp`, the `blobStorageUrl` of the stored file, and a `signature` for integrity verification. The list endpoint supports `$filter`; see the Fleets API reference for the filterable fields.

## Restore a backup

Restore is also a `POST`, with the stored file path from the backup record. It returns `202 Accepted` and applies asynchronously.

```bash
curl -X POST "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/devices/my-device/restore" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "displayName": "Restore pre-update snapshot" },
    "spec": {
      "restoreFilePath": "my-device/<BACKUP_ID>/pre-update-20260415-100000.tar.gz",
      "restoreAssetFile": false
    }
  }'

```

Confirm the backup identity before you restore it onto a live device.

## Upload an external backup

If you already hold a `.tar.gz` backup file, upload it and let MK.IO generate its metadata:

```bash
curl -X POST "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/uploadBackup" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @my-device-backup.tar.gz

```

## What goes wrong

Restoring a backup onto a different Beam server. This is not supported. A backup restores to the device it came from. See the on-device detail in Backup and restore.

* Old backups disappearing. A device keeps up to 30 local backups and deletes the oldest when that limit is reached. Download or upload any you must retain.

* Configuration changes blocked mid-operation. Device configuration access is locked while a backup or restore runs. Wait for it to finish.

## What comes next

* Software and updates: take a backup before changing software state.

* Manage devices: return to the device once protection is in place.