Workers KV API Deprecation: I Probed the Route That Dies

Cloudflare's changelog for July 15, 2026 contains one line that will break somebody's cron job on October 15: the legacy Workers KV REST routes under /accounts/{account_id}/workers/namespaces/* stop working. Ninety days of notice, a drop-in replacement, no drama. I run a click tracker on a KV namespace, and yesterday I enumerated its 861 keys through this exact REST surface for a latency audit. So I did the obvious next thing: I called the dying route with a production token and looked for the deprecation. From the caller's side, it is not there.

Both paths returned HTTP 200 with byte-identical JSON. No Deprecation header, no Sunset header, no Warning. Cloudflare's response envelope even carries a messages[] array built for exactly this kind of announcement — it came back empty. If a script hits the legacy route today, 68 days before the cutoff, nothing in the response says it is running on borrowed time.

What is actually deprecated

The official changelog entry is short: deprecation announced July 15, 2026, end of support October 15, 2026, and the migration is a path substitution. Cloudflare's own wording: "The legacy and replacement routes are interchangeable. They accept the same request parameters and return the same response payloads." The full route list lives in the API deprecations registry:

Scope matters here. This is the account-level REST API only — the surface curl scripts and CI pipelines call. The binding API inside a Worker (env.MY_KV.get()) is a different surface and is not touched. Neither is wrangler, for reasons the audit below makes concrete.

68 days out, the dying route answers like nothing is wrong

All probes ran on August 8, 2026 against the production namespace behind this site's click tracker, read-only. The probe is one line per route:

curl -sD - "https://api.cloudflare.com/client/v4/accounts/$ACCT/workers/namespaces/$NS/keys?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Namespace list, key list, value read, and metadata read all returned 200 on both paths. The JSON payloads were byte-identical for the namespace list and identical except for the opaque pagination cursor on the key list. Both routes report the same api-version: 2026-09-26.epoch header, so they are not even different API generations — they are two doors into the same room.

What I went looking for and did not find: any machine-readable deprecation signal. There is a standard for this, the Sunset header (RFC 8594), whose entire purpose is to let a response say this endpoint stops existing at this timestamp. It is not sent. A monitoring system watching the legacy route will see a perfectly healthy API until the morning it sees a dead one.

Honesty about coverage: I did not test writes, renames, or deletes — this namespace serves live affiliate click counts and I was not going to mutate it from an experiment. The read surface is four of the five deprecated operation groups.

Same JSON, different envelope

The payloads match. The HTTP responses around them do not:

Two observations are useful. The legacy route is the only one that shows its rate-limit budget in the open — q=1200;w=300 is the documented 1,200 requests per 5 minutes, live-counting (r=1199 after one call). And the cookie-plus-cache-header cluster is a fingerprint: if a black-box tool talks to Workers KV and you cannot see its source, the response headers tell you which path it uses without decompiling anything.

A cursor survives switching paths mid-pagination

The interchangeability claim goes deeper than I expected. I took the pagination cursor returned by page one of the legacy key list and passed it to the new path: it continued at exactly the right key (clicks:2026-07-21:neck-lumena, key 11 of the namespace). The reverse direction also worked. So a migration does not need to restart in-flight scans — you can literally swap the URL prefix between page N and page N+1.

One side discovery from the same experiment: limit=3 is rejected with error 10028: limit argument must be at least 10 — identically on both paths, which is itself small evidence that one validator sits behind both doors. Latency was a wash: five samples per route ran 0.31 to 0.51 seconds from Seoul with overlapping ranges, so I am not claiming either path is faster.

Who still ships the legacy path? I went looking

The changelog says who should migrate; it does not say who is actually exposed. So I audited the client ecosystem:

• GitHub code search across the cloudflare org for workers/namespaces: 2 hits total, both in the documentation repo — the deprecation notice itself and the deprecations registry YAML. Zero hits in product code.
• cloudflare-go at v0.9.0, tagged in 2019: already calling storage/kv/namespaces. Same at v0.97.0.
• cloudflare-rs, the client library inside wrangler v1: storage/kv/namespaces.
• terraform-provider-cloudflare, current: built on the new SDK, zero legacy hits.
• The docs as they stood in beta: the Wayback Machine's November 2018 snapshot of the Workers KV API page mentions storage/kv/namespaces nine times and the legacy path zero times.

That last item is the strange one. I could not find a moment when official docs or official clients taught the route that is now being retired — every artifact I checked, back to the 2018 beta, already used storage/kv. The legacy path looks like an alias that outlived any documentation I can locate by roughly seven years. (If you know where it was once documented, I would genuinely like to see it.)

This also means one claim circulating in secondary coverage does not hold up: a write-up of this deprecation states that Terraform users must wait for provider updates before September. The provider has been on the new path through its SDK the whole time, and even the 2019-era Go SDK was. The population actually at risk is narrower and quieter: hand-written curl scripts, CI one-liners, and internal dashboards copied from old gists — artifacts nobody's dependency scanner will ever flag. My own 861-key enumeration from yesterday was exactly this class: an ad-hoc call that lives in no repository.

The one-line audit

Because the fix is a find-and-replace, the whole migration reduces to knowing whether you call the old path anywhere:

grep -rn "workers/namespaces" . --include="*.sh" --include="*.py" \
  --include="*.js" --include="*.yml" --include="*.tf"

My result: zero. The tracker worker touches KV only through its binding, deploys go through wrangler, and the one REST consumer I have (yesterday's key inventory) was never committed. If your grep comes back non-empty, change /workers/namespaces/ to /storage/kv/namespaces/ and you are done — same parameters, same payloads, and even the cursors carry across. The limits I actually watch on this namespace, the free-tier write ceiling and the counter-workload pricing, sit in a different layer and are untouched.

FAQ

Does this affect env.MY_KV.get() inside a Worker?

No. The binding API is not a REST route; it is a runtime interface between your Worker and KV. The deprecation covers only the account-level HTTP endpoints under /client/v4/accounts/…/workers/namespaces/. Workers code needs no change.

Do I need to update wrangler or Terraform for this?

Current versions, no. Wrangler's clients and the Terraform provider have called storage/kv/namespaces since at least 2019 based on the source audit above. The exposure is custom scripts that hardcode the legacy URL, not maintained tooling.

What happens to legacy calls after October 15, 2026?

Cloudflare says the routes "will no longer be supported." As of August 8 there is no Sunset header, no warning message, and no behavioral difference to observe, so plan for a hard failure rather than a graceful one — and since the payloads are identical, the safest move is to switch paths now and not find out.

All probes were run on August 8, 2026 from Seoul against this site's production KV namespace with its own API token: namespace list, key list, value read, and metadata read on both route families, plus the cursor-swap and limit-floor experiments. Writes, renames, and deletes were not tested. The client audit covers GitHub code search over the cloudflare org, cloudflare-go v0.9.0 and v0.97.0, cloudflare-rs, the current Terraform provider, and the Wayback Machine's 2018-11-12 snapshot of the KV API docs; deprecation facts are quoted from Cloudflare's changelog and deprecations registry, read today. Absence of documentation for the legacy path is a search result, not proof it never existed. Some links are affiliate links (my own product); commissions land on the public ledger.