> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pocketbase/pocketbase/llms.txt
> Use this file to discover all available pages before exploring further.

# Backups

> Create, manage, and restore database backups

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

<Warning>
  All backup operations require superuser authentication.
</Warning>

## List backups

Retrieve a list of all available backup files.

```bash theme={null}
GET /api/backups
```

**Authentication:** Superuser required

### Response

Returns an array of backup file information.

<ResponseField name="key" type="string">
  Backup file name/key
</ResponseField>

<ResponseField name="size" type="number">
  File size in bytes
</ResponseField>

<ResponseField name="modified" type="string">
  Last modification timestamp (ISO 8601)
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/backups \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```

  ```json Response theme={null}
  [
    {
      "key": "pb_backup_2024_01_15.zip",
      "size": 1048576,
      "modified": "2024-01-15T10:30:00.000Z"
    },
    {
      "key": "pb_backup_2024_01_14.zip",
      "size": 987654,
      "modified": "2024-01-14T10:30:00.000Z"
    }
  ]
  ```
</CodeGroup>

## Create backup

Create a new backup of the entire database.

```bash theme={null}
POST /api/backups
```

**Authentication:** Superuser required

### Request body

<ParamField body="name" type="string" required>
  Backup file name (must match pattern: `[a-z0-9_-]+\.zip`)
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

  ```bash Auto-generated name theme={null}
  curl -X POST http://127.0.0.1:8090/api/backups \
    -H "Authorization: Bearer SUPERUSER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

<Note>
  If no name is provided, PocketBase generates one automatically based on the current timestamp.
</Note>

### 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

| Code | Description                                       |
| ---- | ------------------------------------------------- |
| 400  | Invalid name format or backup already in progress |
| 401  | Not authenticated as superuser                    |

## Download backup

Download a backup file.

```bash theme={null}
GET /api/backups/{key}
```

<ParamField path="key" type="string" required>
  The backup file key/name
</ParamField>

<ParamField query="token" type="string" required>
  Superuser file token (see Generate file token)
</ParamField>

**Authentication:** File token required (superuser only)

### Response

Returns the backup file as a ZIP archive.

<CodeGroup>
  ```bash Step 1: Generate token theme={null}
  curl -X POST http://127.0.0.1:8090/api/files/token \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```

  ```bash Step 2: Download backup theme={null}
  curl "http://127.0.0.1:8090/api/backups/my_backup.zip?token=FILE_TOKEN" \
    --output backup.zip
  ```
</CodeGroup>

<Note>
  Backup downloads use file tokens instead of auth tokens for security. The token must belong to a superuser account.
</Note>

## Delete backup

Delete a backup file.

```bash theme={null}
DELETE /api/backups/{key}
```

<ParamField path="key" type="string" required>
  The backup file key/name to delete
</ParamField>

**Authentication:** Superuser required

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://127.0.0.1:8090/api/backups/my_backup.zip \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

### Common errors

| Code | Description                                            |
| ---- | ------------------------------------------------------ |
| 400  | Backup is currently in use (being created or restored) |
| 404  | Backup file not found                                  |

## Restore backup

Restore the database from a backup file.

```bash theme={null}
POST /api/backups/{key}/restore
```

<ParamField path="key" type="string" required>
  The backup file key/name to restore
</ParamField>

**Authentication:** Superuser required

### Response

Returns 204 No Content on success. The server will restart after restoring.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/backups/my_backup.zip/restore \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

### 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

| Code | Description                                                    |
| ---- | -------------------------------------------------------------- |
| 400  | Another backup/restore is in progress or backup file not found |
| 500  | Restore operation failed                                       |

## Upload backup

Upload an external backup file to the server.

```bash theme={null}
POST /api/backups/upload
```

**Authentication:** Superuser required

### Request

Use `multipart/form-data` to upload the backup file.

<ParamField body="file" type="file" required>
  The backup ZIP file to upload
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/backups/upload \
    -H "Authorization: Bearer SUPERUSER_TOKEN" \
    -F "file=@/path/to/backup.zip"
  ```
</CodeGroup>

<Note>
  The uploaded backup must be a valid PocketBase backup ZIP file. Invalid or corrupted files will be rejected.
</Note>

## 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

```bash theme={null}
#!/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

<Note>
  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.
</Note>

## 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

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