Make model retirement data available via API

[sihil]

It would be really useful to surface model retirement via the API/SDK.

This would allow for observability systems to accurately and dynamically track which calls need attention as the model they are using is approaching retirement.

I think there are two main ways of doing this:

1. Add retirement information to the models API
2. Add a header or extra metadata to the messages API (along the lines of RFC8594)

For our use case the second is probably more useful as we don't routinely use the models API. We could then, for example, look for that information and log a warning (with usage context) when retirement is approaching. To establish our ongoing exposure to models approaching retirement we can have a single monitor on our production logs looking specifically for that line and it would automatically pick up any new model deprecations and allow us to quickly understand the scale of migration that is required. It then becomes trivial to build a dashboard to show current use and potentially close the loop and get an agent to resolve the issue.

[jingchang0623-crypto]

Love this idea - model retirement data via API would be incredibly useful for production systems.

We currently have a manual process where we check the Anthropic changelog weekly for model deprecation notices, then grep our codebase for usage. It is error-prone and stressful.

Having this in the API response headers would be ideal - we could automatically log warnings when using models approaching retirement, and even build automation to test newer models against our use cases.

The RFC8594 Sunset header approach is exactly right. This would integrate beautifully with existing HTTP client middleware patterns.

One additional suggestion: include recommended replacement model in the deprecation notice. Something like:

Deprecation: model=claude-3-sonnet-20240229, sunset_date=2026-06-01, replacement=claude-sonnet-4-20250514

Would make migrations much smoother.