Skip to main content

​
Endpoint

POST /api/servers/:server/backup/:backup/restore

​
Authentication

Requires Bearer token authentication via the Authorization header.

​
Path Parameters

​
server
string
required
The UUID of the server
​
backup
string
required
The UUID of the backup to restore

​
Request Body

​
adapter
string
required
Backup storage adapter. Valid values: wings (local) or s3
​
truncate_directory
boolean
default:"false"
Whether to delete all existing files before restoring the backup
​
download_url
string
Required for S3 backups. Pre-signed URL to download the backup from S3.

​
Response

Returns 202 Accepted immediately. The restoration process continues asynchronously in the background.

​
Example Request

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup/550e8400-e29b-41d4-a716-446655440000/restore" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter": "wings",
    "truncate_directory": true
  }'

​
Restoration Process

1

Server State Update

Server is marked as “restoring” to prevent modifications during restoration.
2

Optional Truncation

If truncate_directory: true, all existing files in the server directory are deleted.
This is irreversible. All current server data will be lost.
3

Backup Retrieval

Local (wings) adapter:
  • Locates backup in configured backup directory
  • Verifies backup file exists
S3 adapter:
  • Downloads backup from provided download_url
  • Streams download directly to extraction (no disk buffering)
  • Validates Content-Type is application/x-gzip or application/gzip
4

Archive Extraction

  • Extracts tar.gz archive to server directory
  • Preserves file permissions and timestamps
  • Overwrites existing files
5

Completion

  • Server state updated to normal
  • WebSocket event published
  • Panel notified of completion

​
WebSocket Events

Restoration progress is published via WebSocket: 
{
  "event": "daemon message",
  "args": ["Starting restoration process for server backup using local driver"]
}

{
  "event": "backup restore completed",
  "args": [""]
}

​
Behavior

  • Restoration runs asynchronously in the background
  • Server state is set to “restoring” during the process
  • Existing files are preserved unless truncate_directory: true
  • Files in the backup overwrite existing files with the same path
  • Directory structure from backup is recreated
  • Server remains stopped during restoration (if running, stop it first)
The restoration endpoint returns immediately with 202 Accepted. Use WebSocket events to monitor progress.

​
Error Responses

Missing download_url for S3 backup or invalid Content-Type
Missing or invalid Bearer token
Server or backup does not exist
Failed to restore backup (corrupted archive, disk full, etc.)

​
Best Practices

  1. Always stop the server before restoring to prevent file conflicts
  2. Use truncate_directory: true for complete restoration to avoid mixing old and new files
  3. Create a backup before restoring to have a rollback option
  4. Monitor disk space - restoration requires temporary space for extraction
  5. Verify backup integrity in the Panel before restoring

​
Source Reference

Implementation: router/router_server_backup.go:68-172 (postServerRestoreBackup function)

Build docs developers (and LLMs) love

Get started for freeTalk to us