API versioning and deprecation when agents are the consumer

API versioning and deprecation used to be a problem between you and a finite set of developer customers. You shipped a v2, gave the v1 users twelve months, sent a few emails, and the long tail eventually moved. The shape of the contract mattered, but the social contract — humans reading changelogs, humans rewriting client code — did most of the work.

That social contract breaks the moment your primary API consumer is an agent. Agents don't read changelogs. They don't get the migration email. They re-plan from whatever tool definitions they were handed at session start, and they fail silently when those definitions drift from the runtime. This piece argues that versioning and deprecation in the agent era is less about SemVer discipline and more about how you propagate change through a tools layer that sits between your API and the model. We'll cover why the old playbook breaks, what a REST API versioning strategy looks like when agents are first-class consumers, how to design a deprecation policy that actually drains traffic, how to handle breaking changes without taking down a thousand running sessions, and where the tools layer fits in all of this.

Why the old versioning playbook breaks for agents

The traditional REST API versioning strategy assumes a developer somewhere is paying attention. URL versioning (/v1/, /v2/), header versioning, or date-based versioning all rely on the same loop: the API publisher announces a change, a human notices, a human updates the client. The deprecation timeline exists to give that human enough runway.

Agents short-circuit every step of that loop. The model doesn't have a stable client codebase you can grep for v1. It has a tool catalogue handed to it at runtime, usually as JSON schemas. If the underlying endpoint's behaviour changes — a field renamed, an enum value retired, a required parameter added — the model will keep calling the tool with the old shape until the call fails. And when it fails, the model often retries with small perturbations rather than escalating, burning tokens and producing user-visible errors that look like model hallucinations but are actually contract drift.

There's a second-order problem. Most established SaaS products have APIs that were never versioned cleanly to begin with. The /v1/ prefix is there for show; the real surface is a mix of stable endpoints, undocumented behaviours, and per-customer quirks. Human developers tolerated this because they could read the source or ask in a Slack channel. Agents can't. Every undocumented behaviour is either invisible to the agent or a landmine waiting for the model to step on it.

What versioning actually has to do in the agent era

The job of versioning shifts. It still has to give consumers a stable contract, but the consumer is now two-layered: the tools layer that mediates between your API and the model, and the agent runtime that invokes those tools. Each layer has different needs.

The tools layer needs to know, with precision, what the current contract is — not just the endpoint signature, but the semantics: which fields are required, which enums are valid, which combinations of parameters produce which outcomes. The agent runtime needs the tool definitions it was given at session start to remain valid for the duration of the session, or it needs a clear signal that they've changed and the session should re-plan.

That means versioning has to do three things it didn't have to do before:

1. Expose semantics, not just shape. A field's type isn't enough. An agent needs to know that status: "archived" means the record is read-only, not that it's been deleted. Semantic versioning of API behaviour — not just schema — becomes load-bearing.
2. Propagate to tool definitions automatically. If your API changes and your tool schemas don't, the agent is working from a lie. The tools layer needs to regenerate definitions on contract change, not wait for a quarterly catalogue refresh.
3. Support concurrent versions at the tool layer, not just the API layer. Different agents may be running against different versions of the same underlying capability. The tools layer has to hold both contracts simultaneously and route correctly.

This is closer to how Stripe handles API versioning — pinning the version at account creation and maintaining old behaviour indefinitely — than it is to the /v1/ → /v2/ cutover most SaaS APIs run. Stripe's model works because every change is additive at the wire level and the version gate happens server-side. That discipline is rare, but it's the bar agents push you toward.

A deprecation policy that works when consumers can't read email

An API deprecation policy in the human-developer era has three parts: announcement, sunset window, and removal. The announcement is usually a blog post or a changelog entry. The sunset window is typically six to twelve months. Removal is a hard cutoff.

None of those mechanisms work for agents. A blog post doesn't reach an agent. A six-month sunset window assumes someone is watching the calendar. A hard cutoff produces a cliff: working on Monday, broken on Tuesday, no signal in between.

A deprecation policy that survives agent consumption needs four properties:
‍

The Sunset header (RFC 8594) and the Deprecation header (RFC 9745, now a Proposed Standard) are the standard signals for this. They're trivial to add and they travel inside the response, so any consumer — human or agent — that reads them gets the notice. But they only work if the tools layer is configured to read them and surface them into tool metadata. Otherwise they're noise.

The harder discipline is traffic drain. Instead of going from 100% accepted to 100% rejected on the sunset date, you reject a growing percentage of requests over the final weeks, with clear error codes that distinguish "deprecated, please migrate" from "endpoint gone." That gives any consumer — including agents that retry — a chance to learn the call is failing systematically rather than transiently. It also gives your support team data on which consumers haven't migrated, well before the cliff.

Managing breaking API changes without breaking running sessions

The hardest case isn't deprecation, which is gradual by definition. It's the breaking change that has to ship next week — a security fix that requires a new required parameter, a billing change that retires an enum value, a compliance rule that forces a field rename. The kind of change that, in the human-developer era, you'd push with a major version bump and a coordinated migration.

Managing breaking API changes when agents are running against your API in production sessions requires something the old playbook never had: a way to invalidate tool definitions mid-flight without taking down the session.

Three patterns work. They're not mutually exclusive.

Shadow the old contract. Keep the deprecated endpoint live, but route it to a compatibility shim that translates old-shape requests into new-shape calls on the backend. The agent keeps making calls that look like they're working. Your underlying system gets the right data. This buys you weeks, not years — shims are technical debt — but it prevents the cliff.

Re-issue tool definitions. If your tools layer can push updated tool schemas to active agent sessions, the model can re-plan with the new contract. This requires the agent runtime to support mid-session capability changes, and platform support is now real: Anthropic's Claude platform supports live updates to MCP server and tool configurations on active sessions (plus dynamic tool discovery via the Tool Search Tool), and OpenAI's Realtime API exposes a session.update event for re-issuing the tools array mid-session, while the Responses API passes tools per request so they can change between turns. Most third-party agent frameworks still don't expose any of this cleanly.

Error semantically, not syntactically. When a breaking change ships and an agent hits the old contract, the failure response matters enormously. A 500 tells the agent nothing. A 400 with {"error": "parameter_required", "parameter": "customer_id", "reason": "contract_updated", "migration_url": "..."} lets a well-built tools layer translate that into a structured signal the model can act on — either by retrying with the new shape if it has enough context, or by escalating to a human.

The common thread: breaking changes survive better when the contract change is observable from inside the call itself, not just from a changelog the agent will never read.

How Pontil fits

The whole problem of API versioning and deprecation in the agent era assumes a tools layer exists between your API and the model. Most established SaaS companies don't have one. They have an API, possibly versioned, possibly not, and an agent project that talks to it directly or through a thin wrapper. When the API changes, the wrapper drifts, and the agent fails in ways the team only catches when a customer complains.

Pontil is the tools layer for that situation. We generate tool definitions from your existing API surface and codebase, hold them current as your contracts change, and run them against your systems with auth scoped to the real user. That means when you ship a breaking change, the tool definitions regenerate against the new contract automatically — the agent doesn't keep calling a shape that no longer exists. And when you deprecate an endpoint, the runtime can surface that signal into the tool metadata so agents stop reaching for it before the sunset date arrives.

If you want to see how this works against a real API, book a walkthrough.

What versioning looks like five years from now

The interesting question isn't how to retrofit a deprecation policy onto an API designed for human developers. It's what API design looks like when you assume agents are the dominant consumer from day one. Stripe-style additive-only changes become the default. Semantic versioning of behaviour, not just schema, becomes table stakes. Tool definitions become a first-class artefact of the API itself, not a downstream wrapper a team builds on the side.

We're not there yet. Most established SaaS APIs were built for the UI, with developer access bolted on later, and now agents are the third audience trying to use a surface that was never designed for any of the three. Versioning discipline is a way of paying down that debt incrementally — not a substitute for the deeper work of making the product reachable in the first place.

The teams getting this right are the ones who stopped treating versioning as a documentation problem and started treating it as a runtime problem. The contract isn't the OpenAPI file. The contract is what the tools layer hands the model at session start, and whether that matches what the API actually does when the call lands.