Let agents pin the API version they were built against

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); 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

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.