> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/developer-portal/backup-service.md).

# Backup Service API

Trigger and restore backups programmatically.

List, create and restore world backups from your own plugin. Where backups are stored (local disk, SFTP or S3) is set by the server owner in `config.yml` and is the same for API calls; the API cannot change it.

***

## 1. Backup Operations

Manage world backups using the `BackupService` interface, resolved from the root `BuildSystem` instance.

### Checking Backup History

Fetch the `BackupProfile` for a target world to list its existing backups:

```java
import de.eintosti.buildsystem.api.BuildSystem;
import de.eintosti.buildsystem.api.BuildSystemProvider;
import de.eintosti.buildsystem.api.world.BuildWorld;
import de.eintosti.buildsystem.api.world.backup.Backup;
import de.eintosti.buildsystem.api.world.backup.BackupProfile;
import de.eintosti.buildsystem.api.world.backup.BackupService;
import java.util.List;

BackupService backupService = BuildSystemProvider.get().getBackupService();
BackupProfile profile = backupService.getProfile(buildWorld);

// Retrieve all stored backups asynchronously
profile.listBackups().thenAccept(backups -> {
    for (Backup backup : backups) {
        long creationTime = backup.creationTime();
        String backupKey = backup.key(); // Identifier string
    }
});
```

### Programmatic Backup Creation

`createBackup()` saves the world, archives it off the main thread and returns a future with the new `Backup`. Once the new backup is stored, the oldest ones beyond `world.backup.max-backups-per-world` are deleted; a backup that fails deletes nothing. Backups of the same world run one after another, never at the same time.

```java
profile.createBackup().whenComplete((backup, error) -> {
    if (error != null) {
        getLogger().warning("Backup failed: " + error.getMessage());
    }
});
```

### Programmatic Backup Restoration

`restoreBackup(Backup, Player)` replaces the world with the backup. Downloading, checking and extracting the backup run off the main thread while the world is still loaded. Unloading and reloading the world run on the main thread, the folders are then swapped in the background, and the returned future completes on the main thread. If the swap fails, the old world is put back and the future fails. If the old world cannot be put back either, the world stays unloaded and `getLoader().load()` refuses to load it, with a log line naming the leftover folder, until an admin has put the world folder back by hand. Players in the world are moved out only once the backup has been downloaded and checked, and are brought back afterwards. The given player receives the status messages.

```java
import java.util.Comparator;

profile.listBackups().thenAccept(backups -> {
    if (backups.isEmpty()) {
        return;
    }
    Backup newest = backups.stream().max(Comparator.comparingLong(Backup::creationTime)).get();
    // listBackups() completes off the main thread; start the restore on it
    Bukkit.getScheduler().runTask(plugin, () -> profile.restoreBackup(newest, player));
});
```

Call `restoreBackup` from the main thread.

The restore is skipped, with a message to the player and a future that completes normally, when the world is not loaded or when it is the server's default world. Since Paper 26.1 every other world lives inside the default world's folder, so restoring it would delete them all. A backup that cannot be downloaded or read fails the future before the world's files are touched. The future also fails with a `WorldException`, leaving the world as it was, when the world is busy with another operation (a delete, rename, restore, unimport, backup or download) or cannot be unloaded, for example because a listener cancelled `BuildWorldUnloadEvent`. Players already moved out are then sent back. `createBackup()` fails the same way while the world is busy.

***

## 2. Technical Safeguards & Off-Thread Execution

* **Thread use**: Archiving and transfers to S3 or SFTP run on a small, bounded thread pool, away from the server thread. Saving the world and taking it offline or loading it again happen on the main thread. Archives are written to a temporary file and streamed, so world size is not limited by memory.
* **Consistent archives**: While a world is being archived, autosave is paused for it, so region files are not rewritten halfway through being read.
* **Incomplete storage settings**: If the configured S3 or SFTP backend is missing a required setting, BuildSystem logs an error at startup and stores backups locally instead.
* **Backup events**: `BackupCreatedEvent`, `BackupDeletedEvent` (also fired for each backup removed by the per-world limit) and `BackupRestoredEvent` fire on the main thread. See [Event Pipeline](https://buildsystem.eintosti.de/developer-portal/event-pipeline.md).
