Backup API

Create, list, and manage database backups

All backup endpoints require admin role. Unauthorized users will receive a 403 Forbidden response.

Overview

The Backup API provides manual database backup management. Backups are SQLite database snapshots stored in the backups/ directory adjacent to the main database.

Backup files are named mc-backup-YYYY-MM-DD_HH-MM-SS.db and are automatically pruned to maintain the configured retention count (default: 10 backups).

Database Backup Procedure

Mission Control uses SQLite’s built-in backup API to create consistent point-in-time snapshots:

1. Backup is initiated via API or scheduler
2. SQLite performs a hot backup (database remains online)
3. Backup file is written to backups/mc-backup-{timestamp}.db
4. File size and path are logged to audit trail
5. Old backups are automatically pruned if count exceeds retention limit
6. Response includes backup metadata (name, size, timestamp)

Backups capture all tables including agents, tasks, activities, audit logs, and system settings.

List Backups

Retrieve a list of all available backup files sorted by creation time (newest first).

cURL

curl -X GET https://your-domain.com/api/backup \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Response

backups · array

Array of backup file metadata

name · string · required

Backup filename (e.g., mc-backup-2026-03-04_03-00-00.db)

size · integer · required

File size in bytes

created_at · integer · required

Unix timestamp of backup creation

dir · string

Absolute path to the backup directory

Example Response

{
  "backups": [
    {
      "name": "mc-backup-2026-03-04_03-00-00.db",
      "size": 2097152,
      "created_at": 1709524800
    },
    {
      "name": "mc-backup-2026-03-03_03-00-00.db",
      "size": 2048000,
      "created_at": 1709438400
    }
  ],
  "dir": "/var/lib/mission-control/backups"
}

Create Backup

Manually trigger a database backup. This creates an immediate snapshot of the current database state.

cURL

curl -X POST https://your-domain.com/api/backup \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Response

success · boolean · required

Whether the backup was created successfully

backup · object · required

Metadata of the newly created backup

name · string · required

Backup filename

size · integer · required

File size in bytes

created_at · integer · required

Unix timestamp of creation

Example Response

{
  "success": true,
  "backup": {
    "name": "mc-backup-2026-03-04_15-30-22.db",
    "size": 2097152,
    "created_at": 1709569822
  }
}

Backup creation is rate-limited to prevent system overload. The default limit allows 10 backups per hour per admin user.

Automatic Pruning

After creating a backup, the system automatically prunes old backups to maintain the configured retention count:

1. Lists all backup files in the backup directory
2. Sorts by modification time (newest first)
3. Deletes files beyond the retention limit (default: 10)
4. Retention count is configured via general.backup_retention_count setting

Delete Backup

Remove a specific backup file. Useful for managing disk space or removing outdated backups.

cURL

curl -X DELETE https://your-domain.com/api/backup \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "mc-backup-2026-03-01_03-00-00.db"}'

Request Body

name · string · required

Backup filename to delete. Must be a valid .db file without path traversal characters.

Response

success · boolean · required

Whether the backup was deleted successfully

Security

The API validates backup names to prevent path traversal attacks:

• Must end with .db
• Cannot contain / or ..
• Must exist in the backup directory

Deletion is logged to the audit trail with the admin username and deleted filename.

Automated Backups

For automated daily backups, use the Scheduler API:

1. Enable auto-backup via Settings API:

   curl -X PUT https://your-domain.com/api/settings \
     -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"settings": {"general.auto_backup": "true"}}'
   

2. Backups will run daily at 3:00 AM UTC

3. Monitor backup status via Scheduler API:

   curl -X GET https://your-domain.com/api/scheduler \
     -H "Cookie: mc-session=YOUR_SESSION_TOKEN"
   

4. Manually trigger a backup:

   curl -X POST https://your-domain.com/api/scheduler \
     -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"task_id": "auto_backup"}'
   

See Scheduler API for more details on automated backup configuration.

Error Responses

400 Bad Request

Invalid backup name (missing, contains invalid characters, or wrong extension)

401 Unauthorized

User is not authenticated. Check session cookie.

403 Forbidden

User does not have admin role. Only admins can manage backups.

404 Not Found

Backup file not found (DELETE only)

429 Too Many Requests

Rate limit exceeded. Wait before creating another backup.

500 Internal Server Error

Backup operation failed. Check server logs for details.

Backup Best Practices

1. Enable Auto-Backup: Turn on general.auto_backup for daily snapshots
2. Monitor Disk Space: Adjust general.backup_retention_count based on available storage
3. Test Restores: Periodically verify backup integrity by testing restoration
4. Off-Site Storage: Copy backups to external storage for disaster recovery
5. Before Updates: Always create a manual backup before system upgrades

Restoring from Backup

To restore from a backup:

1. Stop the Mission Control service
2. Locate the backup file in the backups/ directory
3. Replace the main database file with the backup:
   cp backups/mc-backup-2026-03-04_03-00-00.db mission-control.db
   
4. Restart the service
5. Verify data integrity via the UI or API