Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document fields and parameters added to support cloud backup #2506

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document fields and parameters added to support cloud backup #2506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 66 additions & 20 deletions docs/api/supervisor/endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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"],
Expand All @@ -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.

:::

</ApiEndpoint>

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

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
Expand Down Expand Up @@ -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:**

Expand Down Expand Up @@ -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`

</ApiEndpoint>

<ApiEndpoint path="/backups/<backup>/info" method="get">
Expand All @@ -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)|

</ApiEndpoint>

<ApiEndpoint path="/backups/<backup>/restore/full" method="post">
Expand All @@ -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:**

Expand All @@ -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:**

Expand Down Expand Up @@ -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"
}
]
}
Expand Down
Loading