Skip to content

Commit d7b7bd4

Browse files
mdegat01mdegat01
committed
Document fields and parameters added to support cloud backup
1 parent 4cafa20 commit d7b7bd4

File tree

2 files changed

+101
-45
lines changed

2 files changed

+101
-45
lines changed

‎docs/api/supervisor/endpoints.md

Lines changed: 66 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -781,8 +781,10 @@ Return a list of [Backups](api/supervisor/models.md#backup)
781781
"name": "Awesome backup",
782782
"type": "partial",
783783
"size": 44,
784+
"size_bytes": 44070259,
784785
"protected": true,
785786
"location": "MountedBackups",
787+
"locations": ["MountedBackups"],
786788
"compressed": true,
787789
"content": {
788790
"homeassistant": true,
@@ -818,9 +820,11 @@ Return information about backup manager.
818820
"name": "Awesome backup",
819821
"type": "partial",
820822
"size": 44,
823+
"size_bytes": 44070259,
821824
"protected": true,
822825
"compressed": true,
823826
"location": null,
827+
"locations": [null],
824828
"content": {
825829
"homeassistant": true,
826830
"addons": ["awesome_addon"],
@@ -845,24 +849,45 @@ Create a full backup.
845849
| name | string | True | The name you want to give the backup |
846850
| password | string | True | The password you want to give the backup |
847851
| compressed | boolean | True | `false` to create uncompressed backups |
848-
| location | string or null | True | Name of a backup mount or `null` for /backup |
852+
| 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 |
849853
| homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup |
850854
| background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. |
855+
| extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases |
851856

852857
**Example response:**
853858

854859
```json
855860
{
856-
"slug": "skuwe823"
861+
"slug": "skuwe823",
862+
"job_id": "abc123"
857863
}
858864
```
859865

866+
:::note
867+
868+
Error responses from this API may also include a `job_id` if the message alone cannot accurately describe what happened.
869+
Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.
870+
871+
:::
872+
860873
</ApiEndpoint>
861874

862875
<ApiEndpoint path="/backups/new/upload" method="post">
863876

864877
Upload a backup.
865878

879+
**Query**
880+
881+
| key | multiple | description |
882+
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
883+
| location | Yes | The name of the backup mount to upload to. Use empty string for `/backup`. Provide multiple locations to upload to multiple places |
884+
885+
*Examples*
886+
887+
- `?location=` - Upload to `/backup`
888+
- `?location=MountedBackups` - Upload to backup mount named `MountedBackup`
889+
- `?location=&location=MountedBackups` - Upload to both of the above places
890+
866891
**Example response:**
867892

868893
```json
@@ -891,15 +916,16 @@ Create a partial backup.
891916
| ------------------------------ | -------------- | -------- | ---------------------------------------------------- |
892917
| name | string | True | The name you want to give the backup |
893918
| password | string | True | The password you want to give the backup |
894-
| homeassistant | boolean | True | Add home assistant core settings to the backup |
895-
| addons | list | True | A list of strings representing add-on slugs |
896-
| folders | list | True | A list of strings representing directories |
919+
| homeassistant | boolean | Content | Add home assistant core settings to the backup |
920+
| 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 |
921+
| folders | list | Content | A list of strings representing directories |
897922
| compressed | boolean | True | `false` to create uncompressed backups |
898-
| location | string or null | True | Name of a backup mount or `null` for /backup |
923+
| 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 |
899924
| homeassistant_exclude_database | boolean | True | Exclude the Home Assistant database file from backup |
900925
| background | boolean | True | Return `job_id` immediately, do not wait for backup to complete. Clients must check job for status and slug. |
926+
| extra | dictionary | True | Extra metadata to store with the backup for client-specific use cases |
901927

902-
**You need to supply at least one key in the payload.**
928+
**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
903929

904930
**Example response:**
905931

@@ -968,6 +994,17 @@ End a freeze initiated by `/backups/freeze` and resume normal behavior in Home A
968994

969995
Download the backup file with the given slug.
970996

997+
**Query**
998+
999+
| key | multiple | description |
1000+
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1001+
| 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)) |
1002+
1003+
*Examples*
1004+
1005+
- `?location=` - Download from `/backup`
1006+
- `?location=MountedBackups` - Download from backup mount named `MountedBackup`
1007+
9711008
</ApiEndpoint>
9721009

9731010
<ApiEndpoint path="/backups/<backup>/info" method="get">
@@ -980,6 +1017,12 @@ Returns a [Backup details model](api/supervisor/models.md#backup-details) for th
9801017

9811018
Removes the backup file with the given slug.
9821019

1020+
**Payload:**
1021+
1022+
| key | type | optional | description |
1023+
| -------- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1024+
| 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)|
1025+
9831026
</ApiEndpoint>
9841027

9851028
<ApiEndpoint path="/backups/<backup>/restore/full" method="post">
@@ -988,10 +1031,11 @@ Does a full restore of the backup with the given slug.
9881031

9891032
**Payload:**
9901033

991-
| key | type | optional | description |
992-
| ---------- | ------- | -------- | ------------------------------------ |
993-
| password | string | True | The password for the backup if any |
994-
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
1034+
| key | type | optional | description |
1035+
| ---------- | -------------- | -------- | ------------------------------------ |
1036+
| password | string | True | The password for the backup if any |
1037+
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
1038+
| 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) |
9951039

9961040
**Example response:**
9971041

@@ -1016,15 +1060,16 @@ Does a partial restore of the backup with the given slug.
10161060

10171061
**Payload:**
10181062

1019-
| key | type | optional | description |
1020-
| ------------- | ------- | -------- | ---------------------------------------------- |
1021-
| homeassistant | boolean | True | `true` if Home Assistant should be restored |
1022-
| addons | list | True | A list of add-on slugs that should be restored |
1023-
| folders | list | True | A list of directories that should be restored |
1024-
| password | string | True | The password for the backup if any |
1025-
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
1063+
| key | type | optional | description |
1064+
| ------------- | -------------- | -------- | ---------------------------------------------- |
1065+
| homeassistant | boolean | Content | `true` if Home Assistant should be restored |
1066+
| addons | list | Content | A list of add-on slugs that should be restored |
1067+
| folders | list | Content | A list of directories that should be restored |
1068+
| password | string | True | The password for the backup if any |
1069+
| background | boolean | True | Return `job_id` immediately, do not wait for restore to complete. Clients must check job for status. |
1070+
| 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) |
10261071

1027-
**You need to supply at least one key in the payload.**
1072+
**You need to supply at least one key of the ones marked "Content" in the optional column in the payload.**
10281073

10291074
**Example response:**
10301075

@@ -2105,7 +2150,8 @@ Returns information about mounts configured in Supervisor
21052150
"server": "server.local",
21062151
"share": "media",
21072152
"state": "active",
2108-
"read_only": false
2153+
"read_only": false,
2154+
"user_path": "/media/my_share"
21092155
}
21102156
]
21112157
}

0 commit comments

Comments
 (0)