Backups

Base: /api/backup

Hytale's built-in universe backups

Handler: BackupHandler

Endpoints

GET /api/backup List backups GET /api/backup/config Backup settings GET /api/backup/status Backup status POST /api/backup/create Create backup DELETE /api/backup Delete backup

GET /api/backup

List backups

Returns all backup zip files with size and date.

Response Example

{
  "backups": [
    {
      "filename": "backup_2026-01-01_01-00-00.zip",
      "size": 10485760,
      "created": 1737000000000,
      "modified": 1737000000000
    }
  ],
  "backup_dir": "/srv/backup",
  "configured": true,
  "total": 1,
  "max_count": 5,
  "archive_max_count": 5
}

cURL

curl -X GET 'http://localhost:5550/api/backup' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Lists the .zip files in the backup folder of the server config (fallback ./backup).

GET /api/backup/config

Backup settings

Returns Hytale's backup configuration (folder, interval, retention).

Response Example

{
  "enabled": true,
  "configured": true,
  "frequency_minutes": 60,
  "directory": "/srv/backup",
  "max_count": 5,
  "archive_max_count": 5
}

cURL

curl -X GET 'http://localhost:5550/api/backup/config' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads the native BackupConfig.

GET /api/backup/status

Backup status

Shows whether a backup is running and the result of the last one.

Response Example

{
  "is_backing_up": false,
  "last_backup_timestamp": 1737000000000,
  "last_backup_error": null
}

cURL

curl -X GET 'http://localhost:5550/api/backup/status' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads the state kept by the handler.

POST /api/backup/create

Create backup

Starts a backup of the universe with Hytale's own backup function.

Response Example

{
  "success": true,
  "filename": "backup_2026-01-01_01-00-00.zip",
  "timestamp": 1737000000000
}

cURL

curl -X POST 'http://localhost:5550/api/backup/create' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Calls Universe.runBackup (saves chunks, zips the universe, rotates old backups); waits up to 120 seconds.

DELETE /api/backup

Delete backup

Deletes one backup file.

Request Body

Field	Type	Required	Description
`filename`	string	Yes	Zip file name, no path

Response Example

{
  "success": true,
  "deleted": "backup_2026-01-01_01-00-00.zip"
}

cURL

curl -X DELETE 'http://localhost:5550/api/backup' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"filename": "2026-10-13_12-00-00.zip"}'

Internal Behavior

Rejects names with .., / or \; deletes the file in the backup folder.