Hetzner Changed Its Storage Box API Under Your Backup Cron: Three Breaks and the Audit Your Automation Owes Itself

On October 21, 2025, Hetzner published a changelog entry that rewired the Storage Box API to match the conventions of its Cloud API — with one breaking change effective immediately and two deprecations carrying a removal date of April 21, 2026. That date is now in the past. If your backup automation still targets the pre-migration fields, it is not running against deprecated endpoints anymore. It is running against removed ones.

The good news: the data path never moved. Your restic snapshots still flow over SFTP to the same 1 TB box that costs about €3.20 a month. What changed is the control plane around it — snapshot schedules, subaccount home directories, snapshot rollbacks — and that is exactly the part a self-hosted platform automates. Here is the full receipt, in one table, then the details.

The breaking change: snapshot plans must say when​

The fields hour and minute in Enable Snapshot Plan used to be optional, and omitting them meant "every hour" and "every minute." That default made it possible — API-only, the Hetzner Console never permitted it — to configure a plan that snapshots every minute for a single day of the month and then nothing for the rest of it. Hetzner notes that no active plan was actually configured that way, but the footgun existed, so both fields became required effective immediately.

For backup tooling this is the highest-blast-radius item of the three, because snapshot plans are the "set and forget" layer. A provisioning script written in 2025 that enables a daily plan by passing only day-of-month and max-snapshots worked fine then and fails now. The failure mode is loud rather than silent — the API rejects the request instead of scheduling something surprising — but "loud at 3 AM during a fleet rebuild" is still the wrong time to discover a missing parameter. If you manage Storage Boxes through Terraform, note that the provider's Storage Box support shipped as experimental, and experimental providers are precisely where a newly-required field takes longest to surface as a clear plan-time error rather than an inscrutable apply-time rejection.

The fix is one line per plan: pin an explicit hour and minute. While you are there, the same entry gave you two new filters worth adopting — username on List Subaccounts and is_automatic on List Snapshots — so the audit script you write to find affected plans can distinguish your scheduled snapshots from manual ones instead of parsing descriptions.

The quiet move: home directory leaves access settings​

In the initial Storage Box API, you changed a subaccount's home directory through the Update Access Settings action. Hetzner now calls that what it was: a bug. A home directory is not an access setting, so it moved to its own Change Home Directory action, and the home_directory property on Update Access Settings was deprecated with removal on April 21, 2026.

This one matters most to platforms using the per-tenant subaccount pattern — one subaccount per tenant, each jailed to its own home directory, all pushing database dumps or volume snapshots to the same box. That pattern is the reason Storage Boxes show up in self-hosted cost breakdowns at all: a BX11's terabyte holds years of gzipped dumps for roughly the price of a coffee, with ten snapshot slots on top for whole-box recovery points. Provisioning a new tenant means creating a subaccount, setting its home directory, and scoping its credentials — and the middle step is the one that moved endpoints.

Any automation still sending home_directory inside an access-settings update has been failing since April. The repair is mechanical: route home-directory changes through the new action and leave access-settings calls to actual access settings (Samba, SSH, WebDAV, read-only flags). And while touching that code, pick up the January 2026 follow-up: subaccounts gained an optional, unique name property, existing subaccounts were migrated to use their username as the name, and the hcloud CLI now addresses subaccounts by ID or name instead of ID or username. If your scripts shell out to hcloud storage-box subaccount describe <box> <username>, they keep working only because the username survived as the name — a coincidence worth converting into an explicit name you control before the next rename.

The rename: rollbacks take a name or an ID​

Rollback Snapshot previously accepted snapshot_id — an ID and only an ID. It now accepts snapshot, which may be either the snapshot's name or its ID, and the old property was deprecated with the same April 21, 2026 removal date.

Of the three changes this is the smallest diff and the easiest to postpone, which is exactly why it deserves a line in your runbook review. Rollback is the endpoint you exercise on your worst day: the restore path, the disaster-recovery drill, the "roll the box back to last night's automatic snapshot" step. A restore script passing snapshot_id worked in every drill before April 2026 and fails in every real incident after it, because nobody drills often enough to have tripped over a removed field. The Cloud-API-consistent payoff is real — accepting names as well as IDs matches how every other Hetzner resource reference works, and combined with the new is_automatic filter you can now resolve "last night's automatic snapshot" by query instead of by tracking IDs in your own state file. But you only get that payoff if you update the call.

There is a second, subtler trap in the same entry for anyone who polls provisioning: storage_box.stats used to be null while a box was initializing and is now a zeroed object. Code that treats a null stats block as "not ready yet" now sees zeros and may proceed against a box still coming up. Check your wait loops for that assumption.

Why this keeps happening: the convergence wave​

The Storage Box migration is not an isolated cleanup. It is one item in a standing Hetzner program of folding second-tier API surfaces into Cloud API conventions, and the changelog reads as a series of dated receipts:

• GET /v1/datacenters and its sibling return HTTP 410 Gone after October 1, 2026 — any capacity-checking logic enumerating datacenters must move to locations.
• The deprecated response field on images, server types, and load balancer types is removed on November 2, 2026 in favor of the structured deprecation object.
• Create endpoints for boxes, subaccounts, and snapshots now return the created resource's ID; list endpoints accept sort; update endpoints accept partial bodies. Each of these closes a gap where the Storage Box surface behaved differently from the Cloud surface your compute automation already speaks.

For a platform team this is the actual thesis of the post: owning the machines does not erase API maintenance, it relocates it. A hosted PaaS absorbs every one of these migrations inside its own control plane and its customers never see a diff. A self-hosted fleet absorbs them in its own backup scripts, Terraform modules, and monitoring checks — one small, dated, eminently automatable migration at a time. The community evidence shows the pattern clearly: monitoring tools like the Storage Box Nagios check cut a v2.0 release specifically to move to the new Console API, and the hcloud CLI's changelog tracks the subaccount naming change field by field. Nobody escaped by ignoring it; everybody paid in one focused upgrade.

The honest accounting is that Hetzner is doing this the right way — announced deprecations with six-month windows, immediate breaks reserved for genuine footguns, convergence toward the better-documented surface. The tax is real but predictable, and predictable taxes can be budgeted: subscribe to the changelog RSS feed, grep your automation for the named fields on every entry, and pin provider and CLI versions so a Sloc-count-small upstream change does not become a restore-day surprise.

The checklist​

1. Search every backup script, Terraform module, and cron job for snapshot_id in a rollback context — replace with snapshot.
2. Search for home_directory inside access-settings calls — route through the Change Home Directory action.
3. Verify every Enable Snapshot Plan call passes explicit hour and minute.
4. Give each subaccount an explicit name instead of relying on the migrated username; update hcloud invocations to address by name.
5. Audit wait loops for the old stats: null means initializing assumption.
6. Adopt the new conveniences while you are in there: create-response IDs instead of re-listing, sort on list calls, username and is_automatic filters, labels at snapshot creation, partial updates.
7. Subscribe to the Hetzner changelog feed and add a recurring calendar item ahead of October 1, 2026 (datacenters 410) and November 2, 2026 (deprecated field removal).

None of this touches the reason Storage Boxes win their slot in a self-hosted backup architecture: roughly €3.20 a month per terabyte, protocols every backup tool already speaks, snapshots scheduled by the platform instead of by your cron. The API around that box now speaks the same dialect as the rest of Hetzner's Cloud API. Pay the migration once, and every future automation you write only has to learn one dialect.

Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own. Star the repo on GitHub or deploy your first app today.