API OpenAPI Breaking Change Detection

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

OpenAPI breaking-change detection helps agents distinguish safe API edits from changes that can break clients.

## Core Explanation

OpenAPI documents describe HTTP API operations, parameters, schemas, and responses. Diffing those documents can catch changes such as removed paths, narrowed enum values, required fields, or response-shape changes before they reach SDKs and integrations.

Agents should not label every API diff as breaking. The decision depends on the compatibility policy, deployed clients, versioning scheme, and whether generated code or runtime validation depends on the changed contract.

## Source-Mapped Facts

- The OpenAPI Initiative describes OpenAPI as a specification for describing HTTP APIs. ([source](https://www.openapis.org/what-is-openapi))
- Bump.sh documentation describes API change management as comparing API definitions to detect changes. ([source](https://docs.bump.sh/help/api-change-management/))
- Speakeasy CLI documentation includes an openapi command group for OpenAPI workflows. ([source](https://www.speakeasy.com/docs/speakeasy-cli/openapi))

## Further Reading

- [OpenAPI Initiative What Is OpenAPI](https://www.openapis.org/what-is-openapi)
- [Bump API Change Management](https://docs.bump.sh/help/api-change-management/)
- [Speakeasy CLI OpenAPI](https://www.speakeasy.com/docs/speakeasy-cli/openapi)