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

# Make only additive 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: Change a live API only by adding optional inputs, response fields, endpoints or enum values. Never remove, rename or retype what clients use.
- How: Treat these as breaking. Removing or renaming a field, adding a required input, tightening validation, changing a default and changing a status code. A new value in a response enum is safe only once clients are told to accept unknown values, as in [tolerant clients](https://agentwranglers.se/playbook/api-design/changes-over-time/tolerant-clients). Check every change against the released contract before it merges.
- Check: A tool such as oasdiff compares the new OpenAPI file with the released one, and the build fails on any breaking change.

Example:

```sh
oasdiff breaking released/openapi.yaml openapi.yaml --fail-on ERR
```

**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/additive-changes`.

- Next: [Version only for breaking changes](https://agentwranglers.se/playbook/api-design/changes-over-time/versioning)
- [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)