> 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
List<Backup> backups = profile.listBackups();
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://buildsystem.eintosti.de/v4/developer-portal/backup-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.