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.

Last synced from FeatherPanel 15b94e9 on 23 Oct 2026.

On this page

Defined in backend/app/routes/user/server/backups.php. Authentication used here: Server access. Read Authentication for how to send credentials and 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 accessDefault rate limit: 5 / minute (user-server-backups)Route name: session-server-recover-backupController: ServerBackupController::recoverBackuproute source

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

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 accessDefault rate limit: 30 / minute (user-server-backups)Route name: session-server-backupsController: ServerBackupController::getBackupsroute source

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

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 accessDefault rate limit: 2 / minute (user-server-backups)Route name: session-server-create-backupController: ServerBackupController::createBackuproute source

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 (application/json) · Response data: 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

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

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 accessDefault rate limit: 2 / minute (user-server-backups)Route name: session-server-create-database-backupController: ServerBackupController::createDatabaseBackuproute source

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

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 accessDefault rate limit: 30 / minute (user-server-backups)Route name: session-server-backup-destinationsController: ServerBackupController::getBackupDestinationsroute source

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

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 accessDefault rate limit: 5 / minute (user-server-backups)Route name: session-server-bulk-delete-backupsController: ServerBackupController::bulkDeleteBackupsroute source

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[]

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

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 accessDefault rate limit: 30 / minute (user-server-backups)Route name: session-server-get-backupController: ServerBackupController::getBackuproute source

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

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

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 accessDefault rate limit: 1 / minute (user-server-backups)Route name: session-server-restore-backupController: ServerBackupController::restoreBackuproute source

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

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

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 accessDefault rate limit: 10 / minute (user-server-backups)Route name: session-server-delete-backupController: ServerBackupController::deleteBackuproute source

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

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

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 accessDefault rate limit: 10 / minute (user-server-backups)Route name: session-server-backup-downloadController: ServerBackupController::getBackupDownloadUrlroute source

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

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

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 accessDefault rate limit: 10 / minute (user-server-backups)Route name: session-server-backup-lockController: ServerBackupController::lockBackuproute source

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

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

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 accessDefault rate limit: 10 / minute (user-server-backups)Route name: session-server-backup-unlockController: ServerBackupController::unlockBackuproute source

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

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

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

Backups endpoints (Client API: game servers)

Endpoints

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

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

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

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

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

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

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

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

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

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

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

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