diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md
index dbbe88a9ce7..d35ca312fc6 100644
--- a/docs/api/supervisor/endpoints.md
+++ b/docs/api/supervisor/endpoints.md
@@ -781,8 +781,16 @@ Return a list of [Backups](api/supervisor/models.md#backup)
"name": "Awesome backup",
"type": "partial",
"size": 44,
+ "size_bytes": 44070259,
"protected": true,
"location": "MountedBackups",
+ "locations": ["MountedBackups"],
+ "location_attributes": {
+ "MountedBackups": {
+ "protected": true,
+ "size_bytes": 44070259
+ }
+ },
"compressed": true,
"content": {
"homeassistant": true,
@@ -818,9 +826,17 @@ Return information about backup manager.
"name": "Awesome backup",
"type": "partial",
"size": 44,
+ "size_bytes": 44070259,
"protected": true,
"compressed": true,
"location": null,
+ "locations": [null],
+ "location_attributes": {
+ ".local": {
+ "protected": true,
+ "size_bytes": 44070259
+ }
+ },
"content": {
"homeassistant": true,
"addons": ["awesome_addon"],
@@ -845,24 +861,48 @@ Create a full backup.
| name | string | True | The name you want to give the backup |
| password | string | True | The password you want to give the backup |
| compressed | boolean | True | `false` to create uncompressed backups |
-| location | string or null | True | Name of a backup mount or `null` for /backup |
+| location | list or string | True | Name of a backup mount or `.local` for `/backup`. Use a list to make the backup in multiple places |
| homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup |
| background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. |
+| extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases |
+| filename | string | True | The name for the backup file created |
**Example response:**
```json
{
- "slug": "skuwe823"
+ "slug": "skuwe823",
+ "job_id": "abc123"
}
```
+:::note
+
+Error responses from this API may also include a `job_id` if the message alone cannot accurately describe what happened.
+Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.
+
+:::
+
Upload a backup.
+**Query**
+
+| key | multiple | description |
+| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| location | Yes | The name of the backup mount to upload to. Use `.local` for `/backup`. Provide multiple locations to upload to multiple places |
+| filename | No | The name for the backup file created |
+
+*Examples*
+
+- `?location=.local` - Upload to `/backup`
+- `?location=MountedBackups` - Upload to backup mount named `MountedBackup`
+- `?location=.local&location=MountedBackups` - Upload to both of the above places
+- `?filename=my_backup.tar` - Create backup file in default backup location with name `my_backup.tar`
+
**Example response:**
```json
@@ -891,15 +931,17 @@ Create a partial backup.
| ------------------------------ | -------------- | -------- | ---------------------------------------------------- |
| name | string | True | The name you want to give the backup |
| password | string | True | The password you want to give the backup |
-| homeassistant | boolean | True | Add home assistant core settings to the backup |
-| addons | list | True | A list of strings representing add-on slugs |
-| folders | list | True | A list of strings representing directories |
+| homeassistant | boolean | Content | Add home assistant core settings to the backup |
+| addons | list or `ALL` | Content | A list of strings representing add-on slugs. Provide the string `ALL` instead of a list to automatically include all add-ons that are currently installed in the system |
+| folders | list | Content | A list of strings representing directories |
| compressed | boolean | True | `false` to create uncompressed backups |
-| location | string or null | True | Name of a backup mount or `null` for /backup |
+| location | list or string | True | Name of a backup mount or `.local` for /backup. Use a list to the make backup in multiple places |
| homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup |
| background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. |
+| extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases |
+| filename | string | True | The name for the backup file created |
-**You need to supply at least one key in the payload.**
+**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
**Example response:**
@@ -968,6 +1010,17 @@ End a freeze initiated by `/backups/freeze` and resume normal behavior in Home A
Download the backup file with the given slug.
+**Query**
+
+| key | multiple | description |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| location | No | Specify which location to download the backup from of the ones it exists in. Use `.local` for `/backup` |
+
+*Examples*
+
+- `?location=.local` - Download from `/backup`
+- `?location=MountedBackups` - Download from backup mount named `MountedBackup`
+
@@ -980,6 +1033,12 @@ Returns a [Backup details model](api/supervisor/models.md#backup-details) for th
Removes the backup file with the given slug.
+**Payload:**
+
+| key | type | optional | description |
+| -------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| location | list | True | Specify which locations to remove the backup from instead of removing it from all locations. See `location_attributes` field from `/backups//info` for locations |
+
@@ -992,6 +1051,7 @@ Does a full restore of the backup with the given slug.
| ---------- | ------- | -------- | ------------------------------------ |
| password | string | True | The password for the backup if any |
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
+| location | string | True | Specify which location to restore the backup from of the ones it exists in. See `location_attributes` field from `/backups//info` for locations |
**Example response:**
@@ -1018,13 +1078,14 @@ Does a partial restore of the backup with the given slug.
| key | type | optional | description |
| ------------- | ------- | -------- | ---------------------------------------------- |
-| homeassistant | boolean | True | `true` if Home Assistant should be restored |
-| addons | list | True | A list of add-on slugs that should be restored |
-| folders | list | True | A list of directories that should be restored |
+| homeassistant | boolean | Content | `true` if Home Assistant should be restored |
+| addons | list | Content | A list of add-on slugs that should be restored |
+| folders | list | Content | A list of directories that should be restored |
| password | string | True | The password for the backup if any |
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
+| location | string | True | Specify which location to restore the backup from of the ones it exists in. See `location_attributes` field from `/backups//info` for locations |
-**You need to supply at least one key in the payload.**
+**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
**Example response:**
@@ -2105,7 +2166,8 @@ Returns information about mounts configured in Supervisor
"server": "server.local",
"share": "media",
"state": "active",
- "read_only": false
+ "read_only": false,
+ "user_path": "/media/my_share"
}
]
}
diff --git a/docs/api/supervisor/models.md b/docs/api/supervisor/models.md
index 97c46c2a86f..99cac35aa9e 100644
--- a/docs/api/supervisor/models.md
+++ b/docs/api/supervisor/models.md
@@ -168,15 +168,27 @@ These models are describing objects that are getting returned from the superviso
## Backup
-| key | type | description |
-| --------- | ------- | --------------------------------------------------------------------- |
-| slug | string | A generated slug for the backup |
-| date | string | ISO date string representation of the date the backup was created |
-| name | string | The name given to the backup |
-| type | string | The type of backup (full, partial) |
-| protected | boolean | `true` if the backup is password protected |
-| content | dictionary | A dictionary describing the content of the backup |
-| compressed | boolean | `true` if the backup is saved in a compressed archive |
+| key | type | deprecated | description |
+| ---------- | -------------- | ---------- | -------------------------------------------------------------------------------------- |
+| slug | string | no | A generated slug for the backup |
+| date | string | no | ISO date string representation of the date the backup was created |
+| name | string | no | The name given to the backup |
+| type | string | no | The type of backup (full, partial) |
+| content | dictionary | no | A dictionary describing the content of the backup |
+| compressed | boolean | no | `true` if the backup is saved in a compressed archive |
+| location_attributes | dictionary | no | A dictionary of [`location_attributes`](#backup---location-attributes) keyed by location the backup exists in. `.local` is the key if backup exists is in local `/backup` folder |
+| size | float | yes | Size of the backup in MB (rounded) |
+| size_bytes | int | yes | Size of the backup in bytes |
+| location | string or null | yes | The name of the backup mount it's stored on. `null` if it's stored locally |
+| locations | list | yes | List of names of all backup mounts it's stored on and/or `null` if it's stored locally |
+| protected | boolean | yes | `true` if the backup is password protected |
+
+### Backup -> location attributes
+
+| key | type | description |
+| ---------- | -------------- | ------------------------------------- |
+| protected | boolean | Backup is password protected |
+| size_bytes | int | Size of the backup in bytes |
### Backup -> content
@@ -190,20 +202,26 @@ The `content` key of a backup object contains the following keys:
## Backup details
-| key | type | description |
-| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| slug | string | A generated slug for the backup |
-| type | string | The type of backup (full, partial) |
-| name | string | The name given to the backup |
-| date | string | ISO date string representation of the date the backup was created |
-| size | string | The size of the backup in MB |
-| protected | boolean | `true` if the backup is password protected |
-| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally. |
-| homeassistant | string | The version of Home Assistant that was in use |
-| addons | list | A list of add-ons in the backup. Add-ons are represented as a dictionary with these keys [`slug`,`name`,`version`,`size`] |
-| repositories | list | A list of add-on repository URL's as strings |
-| folders | list | A list of strings representing directories |
-| homeassistant_exclude_database | boolean | `true` if the Home Assistant database file was excluded from this backup |
+| key | type | deprecated | description |
+| ------------------------------ | -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
+| slug | string | no | A generated slug for the backup |
+| type | string | no | The type of backup (full, partial) |
+| name | string | no | The name given to the backup |
+| date | string | no | ISO date string representation of the date the backup was created |
+| compressed | boolean | no | `true` if the backup is saved in a compressed archive |
+| location_attributes | dictionary | no | A dictionary of [`location_attributes`](#backup---location-attributes) keyed by location the backup exists in. `.local` is the key if backup exists is in local `/backup` folder |
+| supervisor_version | string | no | The version of Supervisor the backup was created on. Backup can only be restored on Supervisor with same version or later |
+| homeassistant | string or null | no | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup |
+| addons | list | no | A list of add-ons in the backup. Add-ons are represented as a dictionary with these keys [`slug`,`name`,`version`,`size`] |
+| repositories | list | no | A list of add-on repository URL's as strings |
+| folders | list | no | A list of strings representing directories |
+| homeassistant_exclude_database | boolean | no | `true` if the Home Assistant database file was excluded from this backup |
+| extra | dictionary | no | A dictionary of extra metadata set by client on creation of the backup |
+| size | float | yes | Size of the backup in MB (rounded) |
+| size_bytes | int | yes | Size of the backup in bytes |
+| location | string or null | yes | The name of the backup mount it's stored on. `null` if it's stored locally |
+| locations | list | yes | List of names of all backup mounts it's stored on and/or `null` if it's stored locally |
+| protected | boolean | yes | `true` if the backup is password protected |
## Stats
@@ -271,19 +289,20 @@ The `content` key of a backup object contains the following keys:
## Mount
-| key | type | description | request/response |
-| ---------- | -------------- | ---------------------------------------------------------------------- | ---------------- |
-| name | string | Name of the mount | both |
-| type | string | Type of the mount (cifs or nfs) | both |
-| usage | string | Usage of the mount (backup, media, or share) | both |
-| server | string | IP address or hostname of the network share server | both |
-| port | int | Port to use (if not using the standard one for the mount type) | both |
-| read_only | bool | Mount is read-only (not available for backup mounts) | both |
-| path | string | (nfs mounts only) Path to mount from the network share | both |
-| share | string | (cifs mounts only) Share to mount from the network share | both |
-| username | string | (cifs mounts only) Username to use for authentication | request only |
-| password | string | (cifs mounts only) Password to use for authentication | request only |
-| state | string | Current state of the mount (active, failed, etc.) | response only |
+| key | type | description | request/response |
+| ---------- | -------------- | ----------------------------------------------------------------------------------------------- | ---------------- |
+| name | string | Name of the mount | both |
+| type | string | Type of the mount (cifs or nfs) | both |
+| usage | string | Usage of the mount (backup, media, or share) | both |
+| server | string | IP address or hostname of the network share server | both |
+| port | int | Port to use (if not using the standard one for the mount type) | both |
+| read_only | bool | Mount is read-only (not available for backup mounts) | both |
+| path | string | (nfs mounts only) Path to mount from the network share | both |
+| share | string | (cifs mounts only) Share to mount from the network share | both |
+| username | string | (cifs mounts only) Username to use for authentication | request only |
+| password | string | (cifs mounts only) Password to use for authentication | request only |
+| state | string | Current state of the mount (active, failed, etc.) | response only |
+| user_path | string or null | Path to the mount in add-ons or Home Assistant if it can be made available there, `null` if not | response only |
Request only fields may be included in requests but will never be in responses.
Response only fields will be in responses but cannot be included in requests.