Deprecating an API When Your Biggest Client Is a Prompt

You ran the deprecation playbook flawlessly. Announcement email six months out. A migration guide with code samples in four languages. Sunset headers on every v1 response. A banner in the developer dashboard. Two reminder emails. Then you turned off v1 — and instead of the quiet cutover the playbook promised, your error rate went vertical and stayed there. Traffic didn't migrate. It just kept arriving, failing, and retrying, at higher volume than before, because every failure triggered another attempt.

The playbook didn't fail because you executed it badly. It failed because it assumes a human is on the other end — someone who reads email, skims changelogs, and files a Jira ticket to migrate before the deadline. A growing share of your traffic has no such person behind it. It comes from agents whose knowledge of your API is frozen in system prompts, tool schemas, and model training data scattered across thousands of repositories you can't see and will never reach. Your sunset notice was written for a reader. Your biggest client is a prompt.

The deprecation playbook assumes someone is listening

Every step of the standard API lifecycle relies on a human eyeball at the right moment. The deprecation email works if someone reads the inbox that receives it. The migration guide works if a developer opens it. The dashboard banner works if anyone logs into the dashboard. Even Sunset headers — the most machine-readable tool in the kit — mostly work because a monitoring library surfaces them to a human who then schedules the migration.

That assumption quietly expired. By mid-2026, automated requests passed human traffic on the web for the first time — Cloudflare's radar put bots at over 57% of HTML traffic — and the agentic slice is the fastest-growing part of it, with AI agent traffic growing several-thousand percent in 2025 alone. APIs were already the majority of web traffic; now a rising fraction of those API calls are composed not by code a developer wrote against your current docs, but by a model deciding at inference time what your API probably looks like.

That distinction matters more than the raw volume. A hand-written SDK integration is stale but legible: it was correct at the moment someone wrote it, and there's a repo where a human can update it. An agent's integration is stale in three layers at once, and two of them have no repo at all.

Where an agent's knowledge of your API actually lives

When an agent calls your API, its beliefs about your endpoints come from some mix of three sources, and every one of them decays on a different clock:

• Model training data. The model memorized your API as it existed across blog posts, Stack Overflow answers, and open-source code at training time — a snapshot that is typically a year or more old by the time the model is in wide production use. Worse, training data is popularity-weighted: if the old endpoint appears in ten thousand repos and the new one in two hundred, the model will confidently emit the old one. This is the same mechanism that makes models reach for deprecated libraries — the deprecated pattern simply has more gravity in the weights.
• System prompts and tool schemas. Someone, somewhere, pasted your endpoint documentation into a system prompt or wrote an MCP tool definition wrapping your API. That text now lives in their repo, their agent platform, their vector store. It will never receive your deprecation email. It gets updated when it breaks badly enough that a human investigates — which is precisely the failure mode a deprecation process exists to prevent.
• Cached documentation in retrieval stores. Teams that do ground their agents in your docs usually do it through a RAG index built from a crawl. If the crawl schedule is quarterly, your six-month deprecation window is two index refreshes — assuming the pipeline still runs and someone re-embedded the changed pages.

Notice what's absent from all three: your changelog. A deprecation notice that never enters the context window may as well not exist. The model doesn't know what it doesn't retrieve, and none of the standard deprecation channels — email, blog post, dashboard — feed any context window anywhere.

Turning off v1 doesn't cause migrations — it causes retry storms

Here's the behavioral difference that breaks the old mental model. When a hand-coded integration hits a dead endpoint, it throws, a pager fires, and a human fixes it. The failure is loud, attributed, and terminal. When an agent hits a dead endpoint, it does what agents are built to do: it copes.

It retries. It rewords the request. It hallucinates a plausible-looking alternative endpoint and tries that. It might decide the error is transient and back off, then try the original again. Multiply that loop across every agent instance holding a stale belief about your API, and turning off v1 doesn't reduce v1 traffic — it amplifies it, converting each would-be request into a small burst of failures, malformed guesses, and retries. Your infrastructure pays for the storm, the agent's operator pays for the wasted tokens, and the end user gets a silently degraded outcome nobody logs as "vendor deprecated the API."

The MCP ecosystem has already given this failure mode a name: silent breakage. A renamed parameter or a removed tool doesn't produce a clean validation error the way a broken SDK build does — it produces an agent that misunderstands its instructions and works around the problem, wrongly, without anyone noticing. The protocol itself versions cleanly, but there is still no standardized versioning layer for individual tools, so schema drift propagates as behavioral drift rather than build failures. Deprecation on the open web is the same problem at larger scale: the consumer doesn't crash, it confabulates.

Loading…