When a provider retires an API

Providers retire things. A model reaches its shutdown date, a version is replaced by the next one, now and then a whole API goes away. For the provider it's a line in a changelog with a date. For everyone who built on it, it's a list of things that break on that date: model ids in config files, keys restricted to certain models, code that reads fields from the answer, cost reports that assume a certain price.

Perplexity's move from Sonar to its Agent API is a good example, because it changed more than model names. This post walks through it.

What Perplexity changed

Perplexity's Sonar models were served over chat completions, the same API shape most tools speak. Perplexity replaced them with its Agent API and retired Sonar chat completions on September 27, 2026. Before that date, it was already refusing Sonar requests from newer API keys, so for some people the retirement had in effect already happened.

The Agent API doesn't just rename the models. Instead of a fixed model, you pick a preset: a model, a reasoning effort, a search budget and a set of tools that Perplexity tunes for a given depth of research. There are five of them, from fast to xhigh.

What Tempr did

Tempr now calls Perplexity on the Agent API, and lists the presets as models:

• perplexity/fast, for single facts and quick summaries
• perplexity/low, for everyday research with light multi-step lookups
• perplexity/medium, for multi-hop research across many sources
• perplexity/high, for exhaustive research
• perplexity/xhigh, for open-ended work that runs code and long tool-use loops

That part is the easy bit. The work is in everything that was built around the old names.

Keeping the old ids working

A model id ends up in a lot of places. It's in your scripts and agent configs. It's in a virtual key's allowlist, where an admin decided which models a key may use. It's the model you picked in your IDE weeks ago and haven't thought about since. If the old ids had stopped working on the retirement date, each of those would have failed separately, and some of them, like an allowlist, would have failed in a way that looks like a permissions problem.

So the Sonar ids keep working, and run as the matching preset:

• sonar runs as fast
• sonar-pro runs as low
• sonar-reasoning-pro runs as medium
• sonar-deep-research runs as high

That includes virtual-key allowlists. A key whose allowlist names perplexity/sonar-pro can use perplexity/low, so nobody has to edit their keys to keep the same access.

In the clients, a saved Sonar model moves to its replacement on its own, so it stays selected and still matches the model list. In VS Code, JetBrains and Visual Studio that covers your chat model, your inline-completion model and the models you set per agent or persona, and in VS Code each saved chat's model too. In the CLI the move happens the next time it starts, and covers your default model, per-persona models and reasoning picks.

Keeping the answer the same shape

Code that reads Perplexity's answers usually cares about the sources. Sonar returned them as citations, a list of URLs where citations[n-1] is the source marked [n] in the text, and as search_results. Answers through Tempr's chat completions endpoint still return both fields, as Sonar did. On /v1/responses the sources come as Perplexity's own search_results output item.

One thing is visibly different: the inline markers. fast cites as [1], and the other presets cite as [web:1]. If you parse those markers, check that your parser accepts both.

Cost and reasoning

On the Agent API, a request's cost is not just tokens. A preset runs its own web searches and page fetches, and Perplexity charges for those too. Tempr bills the cost Perplexity reports for each request, searches included, and returns it as usage.cost, so the number you see is the number Perplexity charged. The prices on the models page are the token rates only, so for these models usage.cost is the figure to trust. The Perplexity section of the provider docs lists the search and fetch rates.

Reasoning works differently too. A preset sets its own reasoning effort, so these models don't offer a reasoning level, and a reasoning or reasoning_effort you send isn't forwarded. If you want deeper reasoning, pick a deeper preset.

Retirements elsewhere

Perplexity is one case. Here is how retirements have gone for other providers in the Gateway.

• Models past their shutdown date leave the list. OpenAI models past their shutdown date are no longer listed, so a model picker doesn't offer something that will only fail.
• Notice before a retirement. Xiaomi stops serving mimo-v2.5 and mimo-v2.5-pro on October 21, 2026 at 02:00 UTC. Our changelog says so ahead of time, with the replacement (MiMo v2.6), and those models leave the list on that date.
• A clear error when there's nothing to move to. Meta shut its Llama API down on July 6, 2026. A request naming one of its models now fails right away with 410 provider_retired, new keys for it aren't accepted, and its models are no longer listed. There's no model it could quietly run instead, so the honest answer is an error that says what happened.

The Sonar mapping works because Perplexity's presets line up with the old models one for one. Where there's no such replacement, as with Llama, a clear error is more useful than a request that quietly runs on a model you didn't ask for.

What you need to do

For Perplexity, nothing. Requests naming Sonar ids keep running, allowlists keep their meaning, and the IDEs and CLI update saved choices on their own. When you next touch a config, you can switch to the preset names, which are what GET /v1/models lists. The changelog lists retirements like these, with their dates.