Skip to main content
The backup endpoints allow you to create and manage server backups, including downloading and restoring them.

​
List Backups

Get all backups for a server. 
curl -X GET "https://panel.example.com/api/client/servers/{server}/backups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
​
server
string
required
The server identifier
​
per_page
integer
Results per page (max 50, default 20)

​
Response

{
  "object": "list",
  "data": [
    {
      "object": "backup",
      "attributes": {
        "uuid": "a1b2c3d4-e5f6-4a5b-8c7d-1e2f3a4b5c6d",
        "name": "Backup 2024-01-15",
        "ignored_files": [],
        "sha256_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "bytes": 524288000,
        "created_at": "2024-01-15T10:30:00+00:00",
        "completed_at": "2024-01-15T10:35:23+00:00",
        "is_successful": true,
        "is_locked": false,
        "checksum_type": "sha256"
      }
    }
  ],
  "meta": {
    "backup_count": 3,
    "pagination": {
      "total": 5,
      "count": 5,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
​
uuid
string
Unique backup identifier
​
name
string
Backup name/description
​
ignored_files
array
File patterns that were excluded from the backup
​
sha256_hash
string
SHA256 checksum of the backup file
​
bytes
integer
Backup size in bytes
​
is_successful
boolean
Whether the backup completed successfully
​
is_locked
boolean
Whether the backup is locked (prevents deletion)
​
completed_at
string|null
ISO 8601 timestamp when backup finished (null if in progress)

​
Get Backup Details

Retrieve information about a specific backup. 
curl -X GET "https://panel.example.com/api/client/servers/{server}/backups/{backup}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
​
backup
string
required
The backup UUID

​
Create Backup

Create a new backup of the server. 
curl -X POST "https://panel.example.com/api/client/servers/{server}/backups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pre-update Backup",
    "is_locked": false,
    "ignored": "*.log\nnode_modules/*\n.git/*"
  }'
​
name
string
Optional backup name (defaults to timestamp)
​
is_locked
boolean
Lock backup to prevent deletion (default: false). Requires backup deletion permission.
​
ignored
string
Newline-separated list of file patterns to exclude from backup

​
Ignore Patterns

File patterns follow standard glob syntax:
  • *.log - All log files
  • cache/* - Everything in cache directory
  • temp/*.tmp - Temporary files in temp directory
  • .git/* - Git repository data

​
Response

Returns the created backup object (same format as list response).
Backup creation is asynchronous. The backup will show completed_at: null until it finishes. Poll the backup details endpoint to check completion status.

​
Download Backup

Generate a signed URL to download a backup. 
curl -X GET "https://panel.example.com/api/client/servers/{server}/backups/{backup}/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

​
Response

{
  "object": "signed_url",
  "attributes": {
    "url": "https://s3.amazonaws.com/bucket/backup.tar.gz?X-Amz-Algorithm=..."
  }
}
​
url
string
Signed download URL (valid for 15 minutes for S3, longer for local storage)
The URL varies based on backup storage:
  • S3/Compatible: Pre-signed S3 URL
  • Local (Wings): Direct download through Wings daemon

​
Lock/Unlock Backup

Toggle the lock status of a backup. Locked backups cannot be deleted. 
curl -X POST "https://panel.example.com/api/client/servers/{server}/backups/{backup}/lock" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

​
Response

Returns the updated backup object with the new is_locked value.
Locking/unlocking backups requires the backup deletion permission.

​
Restore Backup

Restore a server from a backup. 
curl -X POST "https://panel.example.com/api/client/servers/{server}/backups/{backup}/restore" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "truncate": false
  }'
​
truncate
boolean
Whether to delete all existing files before restoring (default: false)

​
Response

Returns 204 No Content when restore begins.
Important Notes:
  • Server must be stopped before restoring
  • Server status will be set to restoring_backup during the process
  • If truncate: true, all existing files will be deleted before extracting the backup
  • If truncate: false, backup files will overwrite existing files with the same name
  • Restore process cannot be cancelled once started

​
Monitoring Restore Progress

Check the server status to monitor restore progress: 
curl -X GET "https://panel.example.com/api/client/servers/{server}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
When status changes from restoring_backup to null, the restore is complete.

​
Delete Backup

Delete a backup. 
curl -X DELETE "https://panel.example.com/api/client/servers/{server}/backups/{backup}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

​
Response

Returns 204 No Content on success.
Deleting a backup is permanent and cannot be undone. Locked backups cannot be deleted until they are unlocked.

​
Backup Limits

The number of backups you can create is limited by your server’s backup_limit configuration: 
{
  "feature_limits": {
    "databases": 5,
    "allocations": 1,
    "backups": 3
  }
}
If you’ve reached the limit, you must delete an existing backup before creating a new one.

​
Backup Storage Types

Pterodactyl supports multiple backup storage backends:

​
Local (Wings)

Backups stored on the Wings daemon server. Pros:
  • Fast backup and restore
  • No external dependencies
  • No additional cost
Cons:
  • Limited by node disk space
  • Not redundant (lost if node fails)
  • Download speeds limited by node bandwidth

​
AWS S3

Backups stored in Amazon S3 or S3-compatible storage (MinIO, Backblaze B2, Wasabi, etc.). Pros:
  • Highly redundant and durable
  • Scalable storage
  • Fast global downloads
Cons:
  • Storage and bandwidth costs
  • Slightly slower initial backup upload
  • Requires S3 configuration

​
Best Practices

​
Regular Backups

Create automated backup schedules: 
# Create a schedule for daily backups at 3 AM
curl -X POST "https://panel.example.com/api/client/servers/{server}/schedules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup",
    "minute": "0",
    "hour": "3",
    "day_of_month": "*",
    "month": "*",
    "day_of_week": "*",
    "is_active": true,
    "only_when_online": false
  }'

# Add backup task to the schedule
curl -X POST "https://panel.example.com/api/client/servers/{server}/schedules/{schedule}/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "backup",
    "payload": "",
    "time_offset": 0
  }'

​
Pre-Update Backups

Always create a locked backup before major updates: 
curl -X POST "https://panel.example.com/api/client/servers/{server}/backups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pre-1.20-Update",
    "is_locked": true
  }'

​
Exclude Unnecessary Files

Reduce backup size and time by excluding logs, cache, and temporary files: 
*.log
logs/*
cache/*
temp/*
*.tmp
.git/*
node_modules/*

Build docs developers (and LLMs) love

Get started for freeTalk to us