diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md
index dbbe88a9..2374b8eb 100644
--- a/docs/api/supervisor/endpoints.md
+++ b/docs/api/supervisor/endpoints.md
@@ -781,8 +781,10 @@ 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"],
"compressed": true,
"content": {
"homeassistant": true,
@@ -818,9 +820,11 @@ Return information about backup manager.
"name": "Awesome backup",
"type": "partial",
"size": 44,
+ "size_bytes": 44070259,
"protected": true,
"compressed": true,
"location": null,
+ "locations": [null],
"content": {
"homeassistant": true,
"addons": ["awesome_addon"],
@@ -845,24 +849,45 @@ 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, string or null | True | Name of a backup mount or `null` for /backup. Use a list of backup mounts or `null` to 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 |
**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 empty string for `/backup`. Provide multiple locations to upload to multiple places |
+
+*Examples*
+
+- `?location=` - Upload to `/backup`
+- `?location=MountedBackups` - Upload to backup mount named `MountedBackup`
+- `?location=&location=MountedBackups` - Upload to both of the above places
+
**Example response:**
```json
@@ -891,15 +916,16 @@ 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 include all currently installed add-ons |
+| 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, string or null | True | Name of a backup mount or `null` for /backup. Use a list of backup mounts or `null` to 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 |
-**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 +994,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 empty string for `/backup` (equivalent to `null` in the `locations` field of [Backup](api/supervisor/models.md#backup)) |
+
+*Examples*
+
+- `?location=` - Download from `/backup`
+- `?location=MountedBackups` - Download from backup mount named `MountedBackup`
+
@@ -980,6 +1017,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 `locations` field of [Backup](api/supervisor/models.md#backup)|
+
@@ -988,10 +1031,11 @@ Does a full restore of the backup with the given slug.
**Payload:**
-| key | type | optional | description |
-| ---------- | ------- | -------- | ------------------------------------ |
-| 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. |
+| key | type | optional | description |
+| ---------- | -------------- | -------- | ------------------------------------ |
+| 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 or null | True | Specify which location to restore the backup from of the ones it exists in. See `locations` field of [Backup](api/supervisor/models.md#backup) |
**Example response:**
@@ -1016,15 +1060,16 @@ Does a partial restore of the backup with the given slug.
**Payload:**
-| 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 |
-| 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. |
+| key | type | optional | description |
+| ------------- | -------------- | -------- | ---------------------------------------------- |
+| 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 or null | True | Specify which location to restore the backup from of the ones it exists in. See `locations` field of [Backup](api/supervisor/models.md#backup) |
-**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 +2150,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 97c46c2a..2497fcae 100644
--- a/docs/api/supervisor/models.md
+++ b/docs/api/supervisor/models.md
@@ -168,15 +168,19 @@ 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 | 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) |
+| size | float | Size of the backup in MB (rounded) |
+| size_bytes | int | Size of the backup in bytes |
+| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally |
+| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally |
+| 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 |
### Backup -> content
@@ -196,14 +200,19 @@ The `content` key of a backup object contains the following keys:
| 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 |
+| size | float | The size of the backup in MB (rounded) |
+| size_bytes | int | Size of the backup in bytes |
+| compressed | boolean | `true` if the backup is saved in a compressed archive |
| 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 |
+| supervisor_version | string | The version of Supervisor the backup was created on. Backup can only be restored on Supervisor with same version or later |
+| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally. |
+| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally |
+| homeassistant | string or null | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup |
| 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 |
+| extra | dictionary | A dictionary of extra metadata set by client on creation of the backup |
## Stats
@@ -271,19 +280,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.