---
title: "Pin their API version and watch for its · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/using-other-companies-apis/pin-and-watch-versions
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Pin their API version and watch for its end

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Using other companies' APIs](https://agentwranglers.se/playbook/api-design/using-other-companies-apis.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: API-79
- Level: Recommended
- Chapter: [Using other companies' APIs](https://agentwranglers.se/playbook/api-design/using-other-companies-apis)
- Rule: Send the provider's API version on every call from one constant in the adapter. Log a warning whenever an answer carries a `Deprecation` or `Sunset` header.
- How: Without a pinned version, the provider can change the answer under you on its own date. Upgrade on purpose, after the tests pass on the new version, as [pin the provider's API version](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/provider-api-version) shows for payments. Read `Deprecation` and `Sunset` on every answer, and send one warning per endpoint a day to the team's alert channel. Subscribe a shared team address to each provider's changelog and status page. How to send these headers from your own API is in [announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers).
- Check: Each adapter has one version constant, and every request in its tests carries it. Make the provider's fake answer with a `Sunset` header. The adapter logs a warning that names the endpoint and the date.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
const CARRIER_API_VERSION = '2026-06-01';

async function carrierFetch(path, init = {}) {
  const response = await fetch(`${CARRIER_URL}${path}`, {
    ...init,
    headers: { ...init.headers, 'carrier-version': CARRIER_API_VERSION },
  });
  const sunset = response.headers.get('sunset');
  if (response.headers.has('deprecation') || sunset) logger.warn({ path, sunset }, 'carrier endpoint deprecated');
  return response;
}
```

### Python example

```python
CARRIER_API_VERSION = "2026-06-01"

def carrier_request(method: str, path: str, **kwargs) -> httpx.Response:
    headers = {**kwargs.pop("headers", {}), "Carrier-Version": CARRIER_API_VERSION}
    response = httpx.request(method, f"{CARRIER_URL}{path}", headers=headers, **kwargs)
    sunset = response.headers.get("Sunset")
    if "Deprecation" in response.headers or sunset:
        logger.warning("carrier endpoint deprecated", extra={"path": path, "sunset": sunset})
    return response
```

## Sources

- [RFC 9745 The Deprecation HTTP response header field](https://www.rfc-editor.org/rfc/rfc9745)
- [RFC 8594 The Sunset HTTP header field](https://www.rfc-editor.org/rfc/rfc8594)

## Related rules

- [Pin the provider's API version](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/provider-api-version) in Payments
- [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/using-other-companies-apis/pin-and-watch-versions">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Decide what happens when a provider is down](https://agentwranglers.se/playbook/api-design/using-other-companies-apis/provider-outages)
- Next: [Give each environment its own provider key](https://agentwranglers.se/playbook/api-design/using-other-companies-apis/key-per-environment)
- [Using other companies' APIs](https://agentwranglers.se/playbook/api-design/using-other-companies-apis)