Implement the Backups API

[lmagyar]

Proposed Changes

Implements the API as https://developers.home-assistant.io/docs/api/supervisor/endpoints/#backup

It caches only the individual backup data (from /backups/${slug}/info), but not the list (/backups/info).

Not implemented: upload(), download()

Related Issues

Summary by CodeRabbit

• New Features
  • Comprehensive backup management: view backup metadata (type, name, date, size, protected, versions, contents)
  • Query, list and filter backups with optional caching and result shaping
  • Create and delete backups (full and partial)
  • Restore backups (full and partial)
  • Freeze, thaw and reload backup state; configure days-until-stale
  • Backup functions available at startup

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4c953df8-461d-4ffc-8dc8-1d4930b6131a

📥 Commits

Reviewing files that changed from the base of the PR and between 8093b0e and 9f3eff3.

📒 Files selected for processing (1)

• lib/backups.sh

🚧 Files skipped from review as they are similar to previous changes (1)

• lib/backups.sh

---

Walkthrough

Adds a new Bashio backups library that implements Supervisor-backed backup management (list, query, create, delete, restore, freeze/thaw, caching, jq filtering, metadata accessors) and sources it into the main bashio library. (50 words)

Changes

Cohort / File(s)	Summary
Backup Module lib/backups.sh	New ~420-line module adding public functions under bashio::backups and bashio::backup for reload, freeze, thaw, days_until_stale, listing (slug/cache key/jq), metadata accessors (type,name,date,size,size_bytes,protected,location,homeassistant_version,supervisor_version,addons,repositories,folders,homeassistant_exclude_database,compressed,homeassistant), create full/partial, delete, restore full/partial. Implements Supervisor API calls, optional per-backup caching, jq filtering, trace logging, exit codes, and cache invalidation on state changes.
Module Integration lib/bashio.sh	Added source "${__BASHIO_LIB_DIR}/backups.sh" to load the new backups module during bashio initialization.

Sequence Diagram

sequenceDiagram
    actor Script as Bash Script
    participant Bashio as Bashio Library
    participant Cache as Local Cache
    participant Supervisor as Supervisor API
    participant Jq as jq Filter

    Script->>Bashio: call bashio::backups* / bashio::backup.*
    alt Cache hit
        Bashio->>Cache: check cached backup info
        Cache-->>Bashio: return cached JSON
    else Cache miss or state-changing op
        Bashio->>Supervisor: GET/POST /backups... endpoints
        Supervisor-->>Bashio: return JSON response
        Bashio->>Cache: store or flush cache
    end
    alt jq filter provided
        Bashio->>Jq: apply jq filter
        Jq-->>Bashio: filtered output or error
    end
    Bashio-->>Script: return JSON or string result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• frenck

Poem

🐇 I hopped through lines with careful care,
Backups tucked in burrows, safe and fair.
Snap, stash, and thaw with carrot-coded cheer,
Small paw prints guard what we hold dear.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Implement the Backups API' directly and accurately describes the main change: adding a new Backups API module with 24 new functions for managing backups via Supervisor endpoints.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@lib/backups.sh`:
- Around line 37-42: The docstring for the "Returns or sets the number of days
until a backup is considered stale." block incorrectly references parameter $2;
update the comment to reference $1 (the first and only argument) so the
docstring matches the implementation that reads the argument into
days_until_stale; specifically change the "$2 Set days_until_stale (Optional)"
line to "$1 Set days_until_stale (Optional)" in the docs for this block.
- Around line 376-382: In bashio::backup.restore_partial() the API path is
wrong; replace the POST call to "/backups/${slug}/partial/full" with the correct
Supervisor endpoint "/backups/${slug}/restore/partial" (keep using
bashio::api.supervisor POST with the same "${options}" argument) so the function
calls the same restore pattern as restore_full; leave the
bashio::cache.flush_all call as-is.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@lib/backups.sh`:
- Around line 37-58: The getter in bashio::backups.days_until_stale calls
bashio::backups with the cache key "backups.days_until_stale", which caches the
filtered result contrary to the intent; update the call inside
bashio::backups.days_until_stale (the branch where no argument is passed) to
pass false as the cache key (i.e., replace the second argument
"backups.days_until_stale" with false) so that when slug="false" the filtered
result is not cached.
- Around line 306-313: The function bashio::backup.homeassistant currently
passes a cache key ("backups.${slug}.homeassistant") when calling
bashio::backups which contradicts the "do not cache backups.info" rule; update
the call in bashio::backup.homeassistant to pass false as the cache key (i.e.,
call bashio::backups with false for the cache key parameter) so the filtered
content.homeassistant from /backups/info is not cached; locate the call inside
function bashio::backup.homeassistant and replace the cache key argument while
keeping the rest of the arguments (the query ".backups[] | select(.slug ==
\"${slug}\") | .content.homeassistant") unchanged.

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[lmagyar]

not stale

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[lmagyar]

not stale

[Copilot]

Pull request overview

Adds a new Bashio module that wraps the Home Assistant Supervisor Backups endpoints, making it possible for add-ons to inspect, create, delete, and restore backups via the existing bashio::api.supervisor helper.

Changes:

• Source a new lib/backups.sh module from the main lib/bashio.sh entrypoint.
• Introduce bashio::backups* and bashio::backup.* functions for backup listing/info access, freeze/thaw, create, delete, and restore operations.
• Implement caching for per-backup info (/backups/${slug}/info) while intentionally not caching the full list payload (/backups/info).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
lib/bashio.sh	Sources the new backups module so its functions are available to add-ons.
lib/backups.sh	New module implementing Supervisor Backups API wrappers, with selective caching and helper accessors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lmagyar]

Now it's ready for human review again.

[frenck]

Thanks, @lmagyar 👍

../Frenck

                       

Blogging my personal ramblings at frenck.dev