41% of APIs drift within 30 days, and most of it is invisible
Schema drift is not usually a breaking change. It is a field nobody told you about, found by a test that failed in CI two weeks later.
KushoAI's State of Agentic API Testing 2026 looked at telemetry from 2,616 organisations and over 1.4 million test executions, and found that 41% of APIs experience schema drift within 30 days. Within 90 days it is 63%.
The number that changes how you should read that: 86% of drift events are field additions.
So the typical drift is not a breaking change. It is a field that appeared in a response and nobody wrote down. That sounds harmless, and the reason it is not harmless is the second finding in the same report: drift is detected reactively, after test failures start appearing in CI. The schema changes first. Somebody notices later.
Why additions are the dangerous case
A removal announces itself. Something stops compiling, a test goes red, a consumer opens a ticket. It hurts immediately and it gets fixed.
An addition is silent by design. Your API returns a new field, every existing consumer ignores it, nothing fails, and your OpenAPI document now describes an API that no longer exists. That gap persists until something depends on it.
Three things then go wrong at once, and none of them looks like a spec problem when it happens:
Your documentation is incomplete rather than wrong. A reader looking for the field you added does not find it, concludes your API cannot do the thing, and either asks support or builds a workaround. You never hear about the ones who built the workaround.
Your generated clients cannot see it. A typed SDK built from the old document has no property for the new field. Your users are getting the data over the wire and cannot reach it without dropping to a raw response, which is exactly the escape hatch that makes a typed client pointless.
Your agent tools describe an API that has moved. An assistant reading your spec has the old shape. It writes code that ignores a field it should have used, and does it confidently.
Where drift actually comes from
Almost always the same place: the spec is a separate artifact from the code.
If your OpenAPI document is hand-maintained in a repo beside your service, drift is not a risk, it is a certainty with a schedule. Someone adds a field in a handler, ships it, and updating the spec is a second task with no forcing function. The 41% figure is not a story about careless teams. It is what happens by default when two things that must agree are updated by two separate actions.
The variants all fail the same way:
Annotation-generated specs drift less, because the spec comes from the code. They drift differently instead: the document reflects the types but not the meaning, so you get complete field lists with no descriptions, no examples, and response schemas that say object.
Spec-first with codegen drifts least, because the code cannot compile away from the document. It costs the most up front and it is the only approach where the question mostly does not arise.
Hand-maintained drifts on the schedule the report measured.
Detecting it before CI does
The report's finding that drift is caught reactively is the actionable part. Reactive detection means the gap between change and discovery is however long it takes for a test to run and someone to read the failure. Two weeks is normal.
Three checks, cheapest first.
Diff the spec against itself on every release. Not a git diff of the file, which shows formatting churn. A semantic comparison of the operation surface: which operations, parameters and response fields exist now that did not before. Most drift is visible here and takes seconds.
Validate real responses against the schema. In staging, sample actual responses and check them against what the spec claims. This is the only check that catches the case where the code changed and the document did not, because it compares the document to reality rather than to its own history.
Watch for the fields your consumers are not using. If you added a field three months ago and no client reads it, either it is undocumented or it is unnecessary. Both are worth knowing.
The version question this raises
Drift and versioning get conflated and they are different problems.
A version tells consumers what changed. Drift is the state where you do not know what changed. You cannot version your way out of drift, because the version number is set by a person who believes the document is accurate.
This is the practical link to generated clients: if your SDK version comes from info.version in your spec, and your spec has drifted, then your package version is a claim about a document rather than about your API. It says "nothing happened" while three fields appeared.
What good looks like
The property to aim for is that changing the API and changing its description are the same action rather than two.
That is achievable in more than one way, and it does not require adopting spec-first. It requires that something fails when they diverge: a contract test, a response validation step in CI, a diff gate on the pull request. Any forcing function beats none, and the absence of one is what the 41% is measuring.
Downstream of that, the argument for generating documentation and clients from the spec rather than maintaining them is the same argument one layer up. If the document is right and everything else derives from it, drift is a single problem with a single fix. If the document, the docs site and six client libraries are each maintained by hand, drift is seven problems that go out of sync at seven different rates.
If you want to know what state your document is in right now, our spec audit scores it against the fourteen rules that decide what can be generated from it, and names the operations that fail each one. It is free, it needs no account, and it does not keep your spec.
And for the other half of this, what counts as a breaking change when your SDK is generated covers which of those drifted fields will actually hurt your consumers when you finally do write them down.
