# Backups endpoints (Client API: game servers)

> 12 FeatherPanel Client API: game servers endpoints from user/server/backups.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/user/server/backups/

Defined in [`backend/app/routes/user/server/backups.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php). Authentication used here: **Server access**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### POST `/api/user/servers/{uuidShort}/backups/{backupUuid}/recover`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-backups`)
- Route name: `session-server-recover-backup`
- Controller: [`ServerBackupController::recoverBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L28)

**Mark a stalled server backup as interrupted** Requires backup.delete permission and confirm\_interrupted=true. Only pending backups at least 24 hours old are eligible. Does not cancel the node job or remove archive files.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | \- | yes |  |
| `backupUuid` | path | \- | yes |  |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID/recover" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Backup marked failed and unlocked · `403` Permission denied · `409` Not stale or concurrently completed

### GET `/api/user/servers/{uuidShort}/backups`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-backups`)
- Route name: `session-server-backups`
- Controller: [`ServerBackupController::getBackups`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L47)

**Get server backups** Retrieve all backups for a specific server that the user owns or has subuser access to.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `page` | query | integer | no | Page number for pagination |
| `per_page` | query | integer | no | Number of records per page |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `data` | Backup\[\] |  |
| `pagination` | BackupPagination |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/backups" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Server backups retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to retrieve backups

### POST `/api/user/servers/{uuidShort}/backups`

- Auth: Server access
- Default rate limit: 2 / minute (`user-server-backups`)
- Route name: `session-server-create-backup`
- Controller: [`ServerBackupController::createBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L70)

**Create backup** Create a new backup for a server. Checks backup limits and initiates backup creation on Wings daemon.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`BackupCreateRequest`](https://featherpanel.com/docs/api/schemas/#schema-backupcreaterequest) (application/json) · Response data: [`BackupCreateResponse`](https://featherpanel.com/docs/api/schemas/#schema-backupcreateresponse)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string | no | Custom backup UUID (optional) |
| `name` | string | no | Backup name (optional) |
| `ignore` | string | no | JSON string of files to ignore (optional) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `id` | integer | Backup ID |
| `uuid` | string | Backup UUID |
| `name` | string | Backup name |
| `adapter` | string | Backup adapter used |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/backups" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uuid":"","name":"","ignore":""}'
```

Plugin events: [`featherpanel:user:server:backup:created`](https://featherpanel.com/docs/plugins/events/server/#server-backup-created)

Responses: `202` Backup creation initiated successfully · `400` Bad request - Missing UUID, backup limit reached, or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to create backup

### POST `/api/user/servers/{uuidShort}/backups/databases`

- Auth: Server access
- Default rate limit: 2 / minute (`user-server-backups`)
- Route name: `session-server-create-database-backup`
- Controller: [`ServerBackupController::createDatabaseBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L96)

**Create database backup files** Export MySQL/MariaDB databases to SQL dumps on the server filesystem. Requires backup.create and database.view\_password.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `databases` | string | integer\[\] | no | "all" or array of database IDs |
| `directory` | string | no | Dump directory on the server filesystem |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/databases" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"databases":[],"directory":""}'
```

Responses: `200` Database backups written successfully · `400` Bad request · `403` Forbidden · `404` Server or node not found · `500` Failed to create database backups

### GET `/api/user/servers/{uuidShort}/backups/destinations`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-backups`)
- Route name: `session-server-backup-destinations`
- Controller: [`ServerBackupController::getBackupDestinations`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L122)

**Get backup destinations** List backup adapters available on the server's node, including the default adapter.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `adapters` | string\[\] |  |
| `destinations` | object\[\] |  |
| `default_adapter` | string |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/destinations" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Backup destinations retrieved · `401` Unauthorized · `403` Forbidden · `404` Server or node not found · `500` Failed to list backup destinations

### DELETE `/api/user/servers/{uuidShort}/backups/bulk-delete`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-backups`)
- Route name: `session-server-bulk-delete-backups`
- Controller: [`ServerBackupController::bulkDeleteBackups`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L145)

**Bulk delete server backups** Delete multiple backups at once. Pass an array of backup UUIDs, or set all=true to delete every unlocked backup. Locked backups are skipped.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `uuids` | string\[\] | no | Backup UUIDs to delete |
| `all` | boolean | no | When true, delete all unlocked backups for the server |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `deleted_count` | integer |  |
| `skipped_count` | integer |  |
| `failed_count` | integer |  |
| `skipped_uuids` | string\[\] |  |
| `failed` | object\[\] |  |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/bulk-delete" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"uuids":[],"all":false}'
```

Plugin events: [`featherpanel:user:server:backup:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-backup-deleted)

Responses: `200` Bulk delete completed · `400` Bad request - Invalid or missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error

### GET `/api/user/servers/{uuidShort}/backups/{backupUuid}`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-backups`)
- Route name: `session-server-get-backup`
- Controller: [`ServerBackupController::getBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L171)

**Get specific backup** Retrieve details of a specific backup for a server that the user owns or has subuser access to.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `backupUuid` | path | string | yes | Backup UUID |

Response data: [`Backup`](https://featherpanel.com/docs/api/schemas/#schema-backup)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `id` | integer | Backup ID |
| `server_id` | integer | Server ID |
| `uuid` | string | Backup UUID |
| `name` | string | Backup name |
| `ignored_files` | string | JSON string of ignored files |
| `disk` | string | Storage disk type |
| `is_successful` | integer | Whether backup was successful (0 or 1) |
| `is_stale` | boolean | Incomplete backup older than 24 hours; eligible for manual interruption recovery |
| `is_locked` | integer | Whether backup is locked (0 or 1) |
| `created_at` | string (date-time) | Backup creation timestamp |
| `updated_at` | string (date-time) | Backup update timestamp |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Backup details retrieved successfully · `400` Bad request - Missing or invalid parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or backup not found · `500` Internal server error - Failed to retrieve backup

### POST `/api/user/servers/{uuidShort}/backups/{backupUuid}/restore`

- Auth: Server access
- Default rate limit: 1 / minute (`user-server-backups`)
- Route name: `session-server-restore-backup`
- Controller: [`ServerBackupController::restoreBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L195)

**Restore backup** Restore a backup to the server. Cannot restore locked backups.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `backupUuid` | path | string | yes | Backup UUID |

Request body: [`BackupRestoreRequest`](https://featherpanel.com/docs/api/schemas/#schema-backuprestorerequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `truncate_directory` | boolean | no | Whether to truncate directory before restore (optional) |
| `download_url` | string | no | Download URL for restore (optional) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID/restore" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"truncate_directory":false,"download_url":""}'
```

Plugin events: [`featherpanel:user:server:backup:restored`](https://featherpanel.com/docs/plugins/events/server/#server-backup-restored)

Responses: `202` Backup restoration initiated successfully · `400` Bad request - Missing parameters or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, backup, or node not found · `423` Locked - Backup is currently locked · `500` Internal server error - Failed to restore backup

### DELETE `/api/user/servers/{uuidShort}/backups/{backupUuid}`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-backups`)
- Route name: `session-server-delete-backup`
- Controller: [`ServerBackupController::deleteBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L222)

**Delete backup** Delete a backup from the server. Cannot delete locked backups.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `backupUuid` | path | string | yes | Backup UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:backup:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-backup-deleted)

Responses: `200` Backup deleted successfully · `400` Bad request - Missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, backup, or node not found · `423` Locked - Backup is currently locked · `500` Internal server error - Failed to delete backup

### GET `/api/user/servers/{uuidShort}/backups/{backupUuid}/download`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-backups`)
- Route name: `session-server-backup-download`
- Controller: [`ServerBackupController::getBackupDownloadUrl`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L249)

**Get backup download URL** Generate a secure download URL for a backup with JWT token authentication.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `backupUuid` | path | string | yes | Backup UUID |

Response data: [`BackupDownloadResponse`](https://featherpanel.com/docs/api/schemas/#schema-backupdownloadresponse)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `download_url` | string | Backup download URL |
| `expires_in` | integer | Token expiration time in seconds |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID/download" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Download URL generated successfully · `400` Bad request - Missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, backup, or node not found · `500` Internal server error - Failed to generate download URL

### POST `/api/user/servers/{uuidShort}/backups/{backupUuid}/lock`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-backups`)
- Route name: `session-server-backup-lock`
- Controller: [`ServerBackupController::lockBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L273)

**Lock backup** Lock a backup to prevent deletion and restoration.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `backupUuid` | path | string | yes | Backup UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID/lock" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:server:backup:lock`](https://featherpanel.com/docs/plugins/events/server/#server-backup-locked)

Responses: `200` Backup locked successfully · `400` Bad request - Missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or backup not found · `500` Internal server error - Failed to lock backup

### POST `/api/user/servers/{uuidShort}/backups/{backupUuid}/unlock`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-backups`)
- Route name: `session-server-backup-unlock`
- Controller: [`ServerBackupController::unlockBackup`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerBackupController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/backups.php#L300)

**Unlock backup** Unlock a backup to allow deletion and restoration.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `backupUuid` | path | string | yes | Backup UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/backups/$BACKUP_UUID/unlock" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:server:backup:unlock`](https://featherpanel.com/docs/plugins/events/server/#server-backup-unlocked)

Responses: `200` Backup unlocked successfully · `400` Bad request - Missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or backup not found · `500` Internal server error - Failed to unlock backup