Backup endpoints
Minimum role: backup (manager and admin also match; GET /backups/info is additionally an info path).
On the v1 tree, partial backup/restore bodies and backup content listings use the addons key; on /v2 the same endpoints use apps. Both are shown below.
| Method | Path | Role | Description |
|---|---|---|---|
| GET | /backups | backup | List backups |
| GET | /backups/info | backup | Backup list plus manager settings |
| POST | /backups/options | backup | Set backup manager options |
| POST | /backups/reload | backup | Rescan backup locations |
| POST | /backups/freeze | backup | Freeze the system for an external backup |
| POST | /backups/thaw | backup | End a manual freeze |
| POST | /backups/new/full | backup | Create a full backup |
| POST | /backups/new/partial | backup | Create a partial backup |
| POST | /backups/new/upload | backup | Upload a backup tar (multipart) |
| GET | /backups/{slug}/info | backup | Backup details |
| DELETE | /backups/{slug} | backup | Remove a backup |
| POST | /backups/{slug}/restore/full | backup | Full restore |
| POST | /backups/{slug}/restore/partial | backup | Partial restore |
| GET | /backups/{slug}/download | backup | Download the backup tar |
Locations
A location value of null, "", or .local means local storage; any other string must name a configured mount with backup usage. A reserved cloud-backup location exists but is accepted only for requests coming from ApexOS Core — any other caller gets 403.
GET /backups
Response data: {"backups": [...]}. Each entry: slug, name, date, type, size, size_bytes, location, locations, protected, location_attributes (per-location protected and size_bytes), compressed, and content — {"apexos": bool, "addons": [slugs], "folders": [...]} (v2: apps instead of addons).
GET /backups/info
Same list plus days_until_stale.
POST /backups/options
| Field | Type |
|---|---|
days_until_stale | int |
POST /backups/freeze
| Field | Type | Description |
|---|---|---|
timeout | int ≥ 1 | Automatic thaw timeout |
POST /backups/new/full
| Field | Type | Default | Description |
|---|---|---|---|
name | string | — | Backup name |
filename | string *.tar | — | Target file name (no path separators) |
password | string | null | — | Encrypt the backup |
compressed | boolean | null | — | Compress archive |
location | string or list | local | One or more target locations |
apexos_exclude_database | boolean | — | Exclude the Core database |
background | boolean | false | Return immediately with job_id |
extra | dict | — | Arbitrary metadata stored with the backup |
Response data: job_id, plus slug when run in the foreground.
POST /backups/new/partial
All full-backup fields, plus:
| Field | Type | Description |
|---|---|---|
addons (v2: apps) | list of slugs or "ALL" | Apps to include; "ALL" expands to every installed app |
folders | list | Folders to include |
apexos | boolean | Include the Core runtime |
POST /backups/new/upload
Multipart upload of a .tar file. Query parameters: location (repeatable) and filename (must match *.tar). Response data: {"slug": "..."}.
GET /backups/{slug}/info
Response data keys: slug, type, name, date, size, size_bytes, compressed, protected, location_attributes, supervisor_version, apexos (Core version in backup), location, locations, addons (v2: apps — each with slug, name, version, size), repositories, folders, apexos_exclude_database, extra.
DELETE /backups/{slug}
| Field | Type | Description |
|---|---|---|
location | string or list | Only remove the copies at these locations |
POST /backups/{slug}/restore/full
| Field | Type | Default |
|---|---|---|
password | string | null | — |
background | boolean | false |
location | string | backup's location |
Response data: {"job_id": "..."}.
POST /backups/{slug}/restore/partial
Full-restore fields plus apexos (boolean), addons (v2: apps, list of slugs), folders (list).
GET /backups/{slug}/download
Returns application/tar. Query parameter location selects which stored copy to stream. Responds 404 (and triggers a location rescan) if the file is missing.