---
title: "Version only for breaking changes · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/changes-over-time/versioning
updated: 2026-10-20
licence: "All rights reserved"
---

# Version only for breaking changes

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Required
- Chapter: [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)
- Rule: Pick one versioning scheme, and release a new major version only when a break can't be avoided.
- How: Put the major version in the path, such as `/v2/orders`, or use a date-based version header, and document which. Run the old version until its sunset date. Never change behaviour inside a version.
- Check: The contract states the scheme, and every route answers under exactly one version.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/changes-over-time/versioning`.

- Previous: [Make only additive changes](https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes)
- Next: [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers)
- [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)