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

# Changes over time

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

> Grow the API by adding, never by breaking. When a break is unavoidable, ship a new version and give clients dates, headers and time to move.

**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`.

## Required

- [Make only additive changes](https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes): Change a live API only by adding optional inputs, response fields, endpoints or enum values. Never remove, rename or retype what clients use.
- [Version only for breaking changes](https://agentwranglers.se/playbook/api-design/changes-over-time/versioning): Pick one versioning scheme, and release a new major version only when a break can't be avoided.
- [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers): Mark a retiring endpoint with the `Deprecation` header and its shutdown date with `Sunset`, and link to the migration guide.

## Recommended

- [Tell clients to ignore what they don't know](https://agentwranglers.se/playbook/api-design/changes-over-time/tolerant-clients): Document that clients must ignore unknown fields and handle unknown enum values, so additions never break them.
- [Keep a changelog](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog): Publish a dated changelog for the API, with every addition, deprecation and removal.

- Previous: [Lists](https://agentwranglers.se/playbook/api-design/lists)
- Next: [Reliability](https://agentwranglers.se/playbook/api-design/reliability)
- [All chapters](https://agentwranglers.se/playbook/api-design)