jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-14 04:46:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document fields added and changed from continued cloud backup effort

Browse Source
This commit is contained in:
Mike Degatano 2025-01-30 15:48:46 -05:00
parent d93a0744e0
commit d905151a96
2 changed files with 82 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
docs/api/supervisor/endpoints.md
View File

@ -785,6 +785,12 @@ Return a list of [Backups](api/supervisor/models.md#backup)
"protected": true, "protected": true,
"location": "MountedBackups", "location": "MountedBackups",
"locations": ["MountedBackups"], "locations": ["MountedBackups"],
"location_attributes": {
"MountedBackups": {
"protected": true,
"size_bytes": 44070259
}
},
"compressed": true, "compressed": true,
"content": { "content": {
"homeassistant": true, "homeassistant": true,
@ -825,6 +831,12 @@ Return information about backup manager.
"compressed": true, "compressed": true,
"location": null, "location": null,
"locations": [null], "locations": [null],
"location_attributes": {
".local": {
"protected": true,
"size_bytes": 44070259
}
},
"content": { "content": {
"homeassistant": true, "homeassistant": true,
"addons": ["awesome_addon"], "addons": ["awesome_addon"],
@ -849,10 +861,11 @@ Create a full backup.
| name | string | True | The name you want to give the backup | | name | string | True | The name you want to give the backup |
| password | string | True | The password 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 | | compressed | boolean | True | `false` to create uncompressed backups |
| 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 | | 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 | | 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. | | 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 | | 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:** **Example response:**
@ -880,13 +893,15 @@ Upload a backup.
| key | multiple | description | | 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 | | 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* *Examples*
- `?location=` - Upload to `/backup` - `?location=.local` - Upload to `/backup`
- `?location=MountedBackups` - Upload to backup mount named `MountedBackup` - `?location=MountedBackups` - Upload to backup mount named `MountedBackup`
- `?location=&location=MountedBackups` - Upload to both of the above places - `?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:** **Example response:**
@ -920,10 +935,11 @@ Create a partial 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 | | 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 | | folders | list | Content | A list of strings representing directories |
| compressed | boolean | True | `false` to create uncompressed backups | | compressed | boolean | True | `false` to create uncompressed backups |
| 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 | | 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 | | 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. | | 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 | | 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 of the ones marked "Content" in the optional column in the payload.** **You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
@ -996,13 +1012,13 @@ Download the backup file with the given slug.
**Query** **Query**
| key | multiple | description | | 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)) | | location | No | Specify which location to download the backup from of the ones it exists in. Use `.local` for `/backup` |
*Examples* *Examples*
- `?location=` - Download from `/backup` - `?location=.local` - Download from `/backup`
- `?location=MountedBackups` - Download from backup mount named `MountedBackup` - `?location=MountedBackups` - Download from backup mount named `MountedBackup`
</ApiEndpoint> </ApiEndpoint>
@ -1019,9 +1035,9 @@ Removes the backup file with the given slug.
**Payload:** **Payload:**
| key | type | optional | description | | 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)| | location | list | True | Specify which locations to remove the backup from instead of removing it from all locations. See `location_attributes` field from `/backups/<backup>/info` for locations |
</ApiEndpoint> </ApiEndpoint>
@ -1031,11 +1047,11 @@ Does a full restore of the backup with the given slug.
**Payload:** **Payload:**
| key | type | optional | description | | key | type | optional | description |
| ---------- | -------------- | -------- | ------------------------------------ | | ---------- | ------- | -------- | ------------------------------------ |
| password | string | True | The password for the backup if any | | 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. | | 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) | | location | string | True | Specify which location to restore the backup from of the ones it exists in. See `location_attributes` field from `/backups/<backup>/info` for locations |
**Example response:** **Example response:**
@ -1060,14 +1076,14 @@ Does a partial restore of the backup with the given slug.
**Payload:** **Payload:**
| key | type | optional | description | | key | type | optional | description |
| ------------- | -------------- | -------- | ---------------------------------------------- | | ------------- | ------- | -------- | ---------------------------------------------- |
| homeassistant | boolean | Content | `true` if Home Assistant 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 | | addons | list | Content | A list of add-on slugs that should be restored |
| folders | list | Content | A list of directories 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 | | 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. | | 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) | | location | string | True | Specify which location to restore the backup from of the ones it exists in. See `location_attributes` field from `/backups/<backup>/info` for locations |
**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.** **You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**

73
docs/api/supervisor/models.md
View File

@ -168,19 +168,27 @@ These models are describing objects that are getting returned from the superviso
## Backup ## Backup
| key | type | description | | key | type | deprecated | description |
| ---------- | -------------- | -------------------------------------------------------------------------------------- | | ---------- | -------------- | ---------- | -------------------------------------------------------------------------------------- |
| slug | string | A generated slug for the backup | | slug | string | no | A generated slug for the backup |
| date | string | ISO date string representation of the date the backup was created | | date | string | no | ISO date string representation of the date the backup was created |
| name | string | The name given to the backup | | name | string | no | The name given to the backup |
| type | string | The type of backup (full, partial) | | type | string | no | The type of backup (full, partial) |
| size | float | Size of the backup in MB (rounded) | | content | dictionary | no | A dictionary describing the content of the backup |
| size_bytes | int | Size of the backup in bytes | | compressed | boolean | no | `true` if the backup is saved in a compressed archive |
| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally | | 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 |
| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally | | size | float | yes | Size of the backup in MB (rounded) |
| protected | boolean | `true` if the backup is password protected | | size_bytes | int | yes | Size of the backup in bytes |
| content | dictionary | A dictionary describing the content of the backup | | location | string or null | yes | The name of the backup mount it's stored on. `null` if it's stored locally |
| compressed | boolean | `true` if the backup is saved in a compressed archive | | 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 ### Backup -> content
@ -194,25 +202,26 @@ The `content` key of a backup object contains the following keys:
## Backup details ## Backup details
| key | type | description | | key | type | deprecated | description |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | ------------------------------ | -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| slug | string | A generated slug for the backup | | slug | string | no | A generated slug for the backup |
| type | string | The type of backup (full, partial) | | type | string | no | The type of backup (full, partial) |
| name | string | The name given to the backup | | name | string | no | The name given to the backup |
| date | string | ISO date string representation of the date the backup was created | | date | string | no | ISO date string representation of the date the backup was created |
| size | float | The size of the backup in MB (rounded) | | compressed | boolean | no | `true` if the backup is saved in a compressed archive |
| size_bytes | int | Size of the backup in bytes | | 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 |
| compressed | boolean | `true` if the backup is saved in a compressed archive | | 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 |
| protected | boolean | `true` if the backup is password protected | | homeassistant | string or null | no | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup |
| supervisor_version | string | The version of Supervisor the backup was created on. Backup can only be restored on Supervisor with same version or later | | 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`] |
| location | string or null | The name of the backup mount it's stored on. `null` if it's stored locally. | | repositories | list | no | A list of add-on repository URL's as strings |
| locations | list | List of names of all backup mounts it's stored on and/or `null` if it's stored locally | | folders | list | no | A list of strings representing directories |
| homeassistant | string or null | The version of Home Assistant that was in use. `null` if Home Assistant is not included in the backup | | homeassistant_exclude_database | boolean | no | `true` if the Home Assistant database file was excluded from this 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`] | | extra | dictionary | no | A dictionary of extra metadata set by client on creation of the backup |
| repositories | list | A list of add-on repository URL's as strings | | size | float | yes | Size of the backup in MB (rounded) |
| folders | list | A list of strings representing directories | | size_bytes | int | yes | Size of the backup in bytes |
| homeassistant_exclude_database | boolean | `true` if the Home Assistant database file was excluded from this backup | | location | string or null | yes | The name of the backup mount it's stored on. `null` if it's stored locally |
| extra | dictionary | A dictionary of extra metadata set by client on creation of the backup | | 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 ## Stats