# AX-SYS-38: Let agents pin the API version they were built against

> Notifications and change · intermediate · AX-SYS-38

Let each caller fix the API version it was built against, per request and per webhook endpoint, and ship breaking changes only in a new version the caller chooses to adopt.

## Why

An agent's tool definitions, prompts and examples are tuned to one shape of your API. If a field is renamed or a parameter becomes required overnight, the agent does not read the changelog first ([AX-SYS-17](ax-sys-17-tell-agents-when-things-change.mdx)); it fails in the middle of a task, or misreads a response that still parses. The fix is to make breaking changes opt-in. GitHub's REST API takes the version in an `X-GitHub-Api-Version` header, releases breaking changes only in a new version, and supports the previous version for at least 24 months after a new one ships. Stripe gives each account a default version, lets any request override it with the `Stripe-Version` header, and sends webhook events in the account's default version unless a version is set on the endpoint, so one integration can see the same shapes in responses and in events. Stripe also advises using versioning to test a new version before committing to an upgrade. For an agent, that means its contract changes when the team behind it decides, after testing, and not when the provider deploys.

## Do

Accept a version header, echo the version used on every response, let webhook endpoints pin a version, and support old versions for a published period.

## Don't

Ship breaking changes to the default version in place, or send webhook payloads in a newer shape than the caller's requests use.

## Artifact

```http
POST /v1/refunds HTTP/1.1
Acme-Version: 2026-06-01

HTTP/1.1 200 OK
Acme-Version: 2026-06-01
Acme-Latest-Version: 2026-09-15
Link: <https://acme.com/docs/upgrades/2026-09-15.md>; rel="help"
```

The agent keeps receiving 2026-06-01 shapes until its team tests 2026-09-15 and changes the header.

## Citations

1. [GitHub Docs: API Versions](https://docs.github.com/en/rest/about-the-rest-api/api-versions): Use the X-GitHub-Api-Version header to specify an API version; breaking changes will be released in a new API version, and when a new version is released the previous one will be supported for at least 24 more months
2. [Stripe API Reference: Versioning](https://docs.stripe.com/api/versioning): Requests use your Stripe account's default API version unless you override it by setting the Stripe-Version header; webhook events also use the account's default version unless an API version is set at endpoint creation; as a precaution, use API versioning to test a new API version before committing to an upgrade

---
Source: Agent Experience Principles (axprinciples.com)