Skip to main content
The Backups API allows superusers to create, download, and restore full database backups. All backup endpoints require superuser authentication.
All backup operations require superuser authentication.

​
List backups

Retrieve a list of all available backup files. 
GET /api/backups
Authentication: Superuser required

​
Response

Returns an array of backup file information.
​
key
string
Backup file name/key
​
size
number
File size in bytes
​
modified
string
Last modification timestamp (ISO 8601)
curl http://127.0.0.1:8090/api/backups \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

​
Create backup

Create a new backup of the entire database. 
POST /api/backups
Authentication: Superuser required

​
Request body

​
name
string
required
Backup file name (must match pattern: [a-z0-9_-]+\.zip)

​
Response

Returns 204 No Content on success. 
curl -X POST http://127.0.0.1:8090/api/backups \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_backup_2024_01_15.zip"}'
If no name is provided, PocketBase generates one automatically based on the current timestamp.

​
Validation

  • Name must be 1-150 characters
  • Only lowercase letters, numbers, hyphens, and underscores allowed
  • Must end with .zip
  • Must be unique (cannot overwrite existing backup)
  • Only one backup/restore operation can run at a time

​
Common errors

CodeDescription
400Invalid name format or backup already in progress
401Not authenticated as superuser

​
Download backup

Download a backup file. 
GET /api/backups/{key}
​
key
string
required
The backup file key/name
​
token
string
required
Superuser file token (see Generate file token)
Authentication: File token required (superuser only)

​
Response

Returns the backup file as a ZIP archive. 
curl -X POST http://127.0.0.1:8090/api/files/token \
  -H "Authorization: Bearer SUPERUSER_TOKEN"
Backup downloads use file tokens instead of auth tokens for security. The token must belong to a superuser account.

​
Delete backup

Delete a backup file. 
DELETE /api/backups/{key}
​
key
string
required
The backup file key/name to delete
Authentication: Superuser required

​
Response

Returns 204 No Content on success. 
curl -X DELETE http://127.0.0.1:8090/api/backups/my_backup.zip \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

​
Common errors

CodeDescription
400Backup is currently in use (being created or restored)
404Backup file not found

​
Restore backup

Restore the database from a backup file. 
POST /api/backups/{key}/restore
​
key
string
required
The backup file key/name to restore
Authentication: Superuser required

​
Response

Returns 204 No Content on success. The server will restart after restoring. 
curl -X POST http://127.0.0.1:8090/api/backups/my_backup.zip/restore \
  -H "Authorization: Bearer SUPERUSER_TOKEN"
Restoring a backup will:
  1. Replace the current database with the backup data
  2. Restart the PocketBase application
  3. Close all active connections
This operation cannot be undone. Always create a current backup before restoring.

​
Restore process

  1. Request is validated
  2. Response is sent (204 No Content)
  3. After ~1 second delay, restore begins
  4. Database is replaced with backup data
  5. Application automatically restarts

​
Common errors

CodeDescription
400Another backup/restore is in progress or backup file not found
500Restore operation failed

​
Upload backup

Upload an external backup file to the server. 
POST /api/backups/upload
Authentication: Superuser required

​
Request

Use multipart/form-data to upload the backup file.
​
file
file
required
The backup ZIP file to upload

​
Response

Returns 204 No Content on success. 
curl -X POST http://127.0.0.1:8090/api/backups/upload \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -F "file=@/path/to/backup.zip"
The uploaded backup must be a valid PocketBase backup ZIP file. Invalid or corrupted files will be rejected.

​
Backup contents

PocketBase backups are ZIP archives containing:
  • Database - SQLite database file (data.db)
  • Storage - All uploaded files from pb_data/storage/
  • Metadata - Backup information and checksums

​
Backup structure

backup.zip
├── data.db           # SQLite database
├── storage/          # All uploaded files
│   ├── collection_id/
│   │   ├── record_id/
│   │   │   └── files...
└── backup.json       # Backup metadata

​
Automated backups

The Backups API is designed for manual operations. For automated backups:
  1. Create a scheduled task/cron job
  2. Call POST /api/backups with superuser auth
  3. Optionally download and store externally

​
Example backup script

#!/bin/bash
SUPERUSER_TOKEN="your_token_here"
BACKUP_NAME="auto_backup_$(date +%Y_%m_%d).zip"

# Create backup
curl -X POST http://127.0.0.1:8090/api/backups \
  -H "Authorization: Bearer $SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$BACKUP_NAME\"}"

# Wait for backup to complete
sleep 5

# Generate file token
TOKEN=$(curl -X POST http://127.0.0.1:8090/api/files/token \
  -H "Authorization: Bearer $SUPERUSER_TOKEN" \
  | jq -r '.token')

# Download backup
curl "http://127.0.0.1:8090/api/backups/$BACKUP_NAME?token=$TOKEN" \
  --output "/backups/$BACKUP_NAME"

​
Storage locations

Backups are stored in the location configured in your PocketBase settings:
  • Local storage: pb_data/backups/
  • S3-compatible: Configured S3 bucket
When using S3 storage, backups may not be immediately available due to eventual consistency. Wait a few seconds after creation before attempting to list or download.

​
Best practices

  1. Regular backups - Schedule automated backups daily or more frequently
  2. Off-site storage - Download and store backups externally
  3. Test restores - Periodically test backup restoration
  4. Backup before changes - Always backup before schema changes or major updates
  5. Retention policy - Delete old backups to manage storage

​
Performance considerations

  • Backup creation locks the database briefly
  • Large databases may take several minutes to backup
  • Only one backup/restore operation can run at a time
  • Restore operations require application restart

​
Common errors

CodeDescription
400Invalid backup name, operation in progress, or missing file
401Not authenticated as superuser
403File token doesn’t belong to superuser
404Backup file not found
500Backup/restore operation failed

Build docs developers (and LLMs) love

Get started for freeTalk to us