Backup and restore tools reference

Regular backups protect your UniFi configuration against accidental changes, hardware failure, and human error. The backup tools let your AI assistant trigger on-demand backups, list what’s available, download files to local storage, and configure recurring backup schedules — all without leaving your conversation.

Restore operations are destructive. Restoring a backup will overwrite your current controller configuration and may cause a controller restart, temporarily disconnecting managed devices. Always pass confirm=True explicitly and consider leaving create_pre_restore_backup=True (the default) enabled so you have a rollback point.

Tools

`trigger_backup`

Creates a new backup immediately. The operation completes synchronously and returns the backup filename and a download URL.

string

required

The site identifier.

string

required

The scope of the backup. Accepted values:

network — network settings and device configurations only. Faster and smaller (typically under 10 MB).
system — complete OS, application, and device configurations. Comprehensive but larger (can exceed 100 MB).

integer

How many days to keep the backup on the controller before automatic deletion. Use -1 for indefinite retention. Defaults to 30.

boolean

required

Must be true to trigger the backup.

boolean

When true, returns what would be created without actually creating the backup.

Example response

{
  "backup_id": "backup_20251115_030000",
  "filename": "backup_2025-11-15_03-00-00.unf",
  "download_url": "/data/backup/backup_2025-11-15_03-00-00.unf",
  "backup_type": "network",
  "created_at": "2025-11-15T03:00:05Z",
  "retention_days": 30,
  "status": "completed"
}

`list_backups`

Returns all backup files available on the controller, including filename, size, creation date, type, and whether each backup is valid.

string

required

The site identifier.

Example response

[
  {
    "backup_id": "backup_20251115_030000",
    "filename": "backup_2025-11-15_03-00-00.unf",
    "backup_type": "NETWORK",
    "created_at": "2025-11-15T03:00:05Z",
    "size_bytes": 4194304,
    "version": "8.4.62",
    "is_valid": true,
    "cloud_synced": false
  }
]

`get_backup_details`

Returns detailed metadata for a single backup file identified by filename.

string

required

The site identifier.

string

required

The exact filename of the backup (e.g., "backup_2025-11-15_03-00-00.unf").

`download_backup`

Downloads a backup file from the controller and saves it to a local path. Optionally calculates a SHA-256 checksum to verify file integrity.

string

required

The site identifier.

string

required

The exact filename of the backup to download.

string

required

The local filesystem path where the backup should be saved (e.g., "/backups/unifi_2025-11-15.unf"). Parent directories are created automatically.

boolean

When true, a SHA-256 hash of the downloaded file is calculated and returned. Defaults to true.

Example response

{
  "backup_filename": "backup_2025-11-15_03-00-00.unf",
  "local_path": "/backups/unifi_2025-11-15.unf",
  "size_bytes": 4194304,
  "checksum": "a3f5b2c1d4e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
  "download_time": "2025-11-15T04:12:00Z"
}

`delete_backup`

Permanently removes a backup file from the controller. This cannot be undone.

string

required

The site identifier.

string

required

The exact filename of the backup to delete.

boolean

required

Must be true to delete the backup.

boolean

Preview the deletion without applying it.

`restore_backup`

Restores the controller from a backup file. This is a destructive operation — the current configuration will be overwritten. By default, the tool creates a safety backup of the current state before initiating the restore, giving you a rollback option if anything goes wrong.

string

required

The site identifier.

string

required

The exact filename of the backup to restore from.

boolean

When true (the default), the tool automatically creates a network backup of the current state before restoring. This backup is retained for 7 days.

boolean

required

Must be true to initiate the restore. This is intentionally a hard requirement given the destructive nature of the operation.

boolean

Preview what the restore would do without initiating it.

After calling restore_backup, the controller may restart. Managed devices may temporarily disconnect during the restart. Expect a connection gap of 2–5 minutes. Do not close your MCP session immediately — wait for the controller to come back online before verifying the result.

`validate_backup`

Checks a backup file for integrity and reports any warnings or errors before you commit to restoring it.

string

required

The site identifier.

string

required

The exact filename of the backup to validate.

Example response

{
  "backup_filename": "backup_2025-11-15_03-00-00.unf",
  "is_valid": true,
  "checksum_valid": true,
  "format_valid": true,
  "version_compatible": true,
  "backup_version": "8.4.62",
  "warnings": [],
  "errors": [],
  "size_bytes": 4194304,
  "validated_at": "2025-11-20T10:00:00Z"
}

`schedule_backups`

Configures a recurring automated backup schedule. Once set, the controller will trigger backups automatically at the specified frequency and time without further intervention.

string

required

The site identifier.

string

required

Scope of scheduled backups: network or system.

string

required

How often to run. Accepted values: daily, weekly, monthly.

string

required

The time to run the backup in 24-hour HH:MM format (e.g., "03:00" for 3 AM). Schedule during low-traffic hours.

boolean

Whether the schedule is active. Defaults to true.

integer

How long to keep each backup (1–365). Defaults to 30.

integer

Maximum number of backups to keep on the controller (1–100). Older backups are deleted when this limit is reached. Defaults to 10.

integer

Required when frequency is weekly. The day to run: 0 = Monday through 6 = Sunday.

integer

Required when frequency is monthly. The day of the month to run (1–31).

boolean

When true, syncs each completed backup to the UniFi cloud. Requires a linked UniFi account.

boolean

required

Must be true to configure the schedule.

boolean

Preview the schedule configuration without applying it.

`get_backup_schedule`

Returns the currently configured automated backup schedule for a site, or indicates that no schedule is set.

string

required

The site identifier.

Schedule examples

Goal	`frequency`	`time_of_day`	Additional params
Daily network backup at 3 AM	`daily`	`"03:00"`	—
Weekly system backup, Sundays at 2 AM	`weekly`	`"02:00"`	`day_of_week=6`
Monthly backup on the 1st at midnight	`monthly`	`"00:00"`	`day_of_month=1`

Example: safe backup before a config change

This workflow shows the recommended practice of creating a backup, verifying it, making your configuration change, and then cleaning up older backups.

# Step 1: Create a backup before making changes
result = trigger_backup(
    site_id="default",
    backup_type="network",
    retention_days=7,
    confirm=True
)
filename = result["filename"]  # e.g., "backup_2025-11-15_10-30-00.unf"

# Step 2: Validate the backup
validation = validate_backup(site_id="default", backup_filename=filename)
assert validation["is_valid"], f"Backup invalid: {validation['errors']}"

# Step 3: Download a local copy for extra safety
download_backup(
    site_id="default",
    backup_filename=filename,
    output_path=f"/backups/{filename}",
    verify_checksum=True
)

# ... make your configuration changes here ...

# Step 4: Set up a daily schedule if not already configured
schedule_backups(
    site_id="default",
    backup_type="network",
    frequency="daily",
    time_of_day="03:00",
    retention_days=30,
    max_backups=10,
    confirm=True
)

For production environments, use frequency="daily" with cloud_backup_enabled=True. System backups are heavier but provide full recovery; network backups are sufficient for most configuration-only changes.

Overview

Read Operations

Write Operations

Security & Access

Operations

Backup and restore tools reference

Tools

`trigger_backup`

`list_backups`

`get_backup_details`

`download_backup`

`delete_backup`

`restore_backup`

`validate_backup`

`schedule_backups`

`get_backup_schedule`

Schedule examples

Example: safe backup before a config change

​Tools

​trigger_backup

​list_backups

​get_backup_details

​download_backup

​delete_backup

​restore_backup

​validate_backup

​schedule_backups

​get_backup_schedule

​Schedule examples

​Example: safe backup before a config change

Tools

`trigger_backup`

`list_backups`

`get_backup_details`

`download_backup`

`delete_backup`

`restore_backup`

`validate_backup`

`schedule_backups`

`get_backup_schedule`

Schedule examples

Example: safe backup before a config change