Skip to main content

​
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 -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/"
  }'

​
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

Invalid adapter type or missing required fields
Missing or invalid Bearer token
Server does not exist
A backup with this UUID already exists
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)

Build docs developers (and LLMs) love

Get started for freeTalk to us