Create Backup

Create a backup of a server

Endpoint

POST /api/servers/:server/backup

Authentication

Requires Bearer token authentication via the Authorization header.

Path Parameters

server · string · required

The UUID of the server

Request Body

adapter · string · required

Backup storage adapter. Valid values: wings (local) or s3

uuid · string · required

UUID for the backup (generated by Panel)

ignore · string

Newline-separated list of files/directories to exclude from backup (same format as .pteroignore)

Response

Returns 202 Accepted immediately. The backup process continues asynchronously.

Example Request

cURL - Local Backup

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

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

await fetch(
  'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      adapter: 'wings',
      uuid: '550e8400-e29b-41d4-a716-446655440000',
      ignore: '*.log\ntemp/\ncache/'
    })
  }
);

import requests

requests.post(
    'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'adapter': 'wings',
        'uuid': '550e8400-e29b-41d4-a716-446655440000',
        'ignore': '*.log\ntemp/\ncache/'
    }
)

Backup Process

1. Backup Initiated

   Wings accepts the request and returns 202 Accepted immediately.

2. Archive Creation

   Creates a gzip-compressed tar archive (.tar.gz) of the server directory.

   • Excludes files matching patterns in the ignore parameter
   • Excludes files listed in .pteroignore file in server root
   • Calculates SHA1 checksum of the archive
3. Storage Upload

   Local (wings) adapter:

   • Saves backup to the configured backup directory
   • Default: /var/lib/pterodactyl/backups/

   S3 adapter:

   • Uploads backup to configured S3 bucket using multipart upload
   • Chunk size: 5 MB per part
   • Uses configured S3 credentials from Wings config
4. Panel Notification

   Wings notifies the Panel when the backup is complete with:

   • Backup size
   • SHA1 checksum
   • Success/failure status

Ignore Patterns

The ignore parameter supports glob patterns:

• *.log - Ignore all .log files
• temp/ - Ignore temp directory
• cache/** - Ignore cache directory and all contents
• node_modules/ - Ignore node_modules
• *.tmp - Ignore temporary files

Patterns are matched using the same rules as .gitignore files.

WebSocket Events

Backup progress is published via WebSocket:

{
  "event": "backup progress",
  "args": ["Creating backup archive..."]
}

{
  "event": "backup complete",
  "args": ["550e8400-e29b-41d4-a716-446655440000"]
}

Behavior

• Backup runs asynchronously in the background
• Server can remain running during backup
• Disk I/O is rate-limited to prevent performance impact (configured via system.backup_write_limit)
• Multiple backups can run concurrently (not recommended)
• Backup filename format: backup-{uuid}.tar.gz

Creating backups of large servers can consume significant disk space and I/O. Monitor disk usage carefully.

Error Responses

400 Bad Request

Invalid adapter type or missing required fields

401 Unauthorized

Missing or invalid Bearer token

404 Not Found

Server does not exist

409 Conflict

A backup with this UUID already exists

500 Internal Server Error

Failed to create backup (disk full, S3 error, etc.)

Configuration

Backup behavior can be configured in config.yml:

system:
  backup_directory: /var/lib/pterodactyl/backups
  backup_write_limit: 0  # 0 = unlimited, otherwise bytes/second

For S3 backups, configure S3 settings in the Panel.

Source Reference

Implementation: router/router_server_backup.go:19-57 (postServerBackup function)