> 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/v4/developer-portal/backup-service.md).

# Backup Service API

Interact with BuildSystem's backup scheduler, configure storage credentials, and execute restores programmatically.

***

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

Trigger an off-thread backup execution:

```java
// Starts asynchronous backup generation
profile.createBackup(); 
```

### Programmatic Backup Restoration

Restore a world state using a reference to a `Backup`. This task executes off-thread.

```java
import org.bukkit.entity.Player;

Backup targetBackup = backups.get(0); // Choose target
Player playerAudience = event.getPlayer(); // Audience to receive status logs

// Executes asynchronous restoration sequence
profile.restoreBackup(targetBackup, playerAudience); 
```

***

## 2. Technical Safeguards & Off-Thread Execution

* **Thread Optimization**: The backup service allocates a bounded background executor to run file compression (ZIP/Tarball operations) and remote transfers (S3, SFTP). This isolates resource-heavy IO operations from the Bukkit server tick thread.
* **Storage Provider Failures**: Storage credential resolution and handshake checks execute before world archiving starts. SFTP storage issues raise standard `IOException` failures immediately, protecting active memory states from silent failures.