API COMPATIBILITY GUIDE

Breaking API changes: requests and responses have different rules.

By Soumik Ghosh · Published 1 November 2026

A request change can reject a value your application already sends. A response change can remove a guarantee your application already relies on. Two captured specification changes show why compatibility needs a direction before it needs a verdict.

What makes an API change breaking?

A contract change is breaking when an existing integration can no longer rely on the accepted requests or promised responses from the previous contract. A specification finding identifies that risk; it does not establish that your code uses the affected operation or that a live request failed. Keep those questions separate when deciding what to change.

Request narrowing: Sentry removes accepted query values

In the Sentry specification captured on 24 October 2026, the field query parameter for GET /api/0/organizations/{organization_id_or_slug}/replays/no longer accepted info_ids and warning_ids. A caller selecting one of those values no longer fits the revised specification.

GET /api/0/organizations/example/replays/?field=info_ids

This is an illustrative request, not a request sent by this guide. ParityDiff records the contract decision as Breaking, with rule request.enum_removed. Before editing a repository, locate the query construction and confirm whether your application still needs the removed value. The contract diff does not supply a replacement.

Inspect the captured Sentry release and source evidence.

Response widening: OpenAI makes a URL optional

In an OpenAI specification transition captured on 16 October 2026, the URL on a web-search find action under the POST /responses/compact response became optional. The revised schema permits an action without that field. A consumer that always parses the URL must now account for its absence.

if (typeof action.url === 'string') {
  inspectSearchUrl(action.url);
} else {
  handleMissingSearchUrl(action);
}

This is an illustrative handling pattern, not a generated or validated fix for a particular application. The recorded classification rule is response.now_optional_or_nullable. Choose the missing-value behavior from your application's requirements, then test it against the response variants your integration supports.

Inspect the captured OpenAI release and source evidence.

Compare schemas in the direction your integration uses

For a request schema, check whether the old accepted inputs remain accepted by the new schema. For a response schema, check whether the new possible outputs still fit the old consumer contract. The online JSON Schema comparison reports equivalent, different, or undetermined and separates the two acceptance directions. A validated counterexample demonstrates a specific difference. An undetermined result requires more evidence.

Compare public or illustrative JSON Schemas, or replay the captured compatibility examples. The playground replays OpenAPI detector findings; it does not provide a complete arbitrary OpenAPI upload diff.

Move from a contract finding to a code decision

1. Inspect the exact operation, changed field, source revisions, and classification rule.
2. Trace supported SDK or HTTP usage to the repositories and commit you authorized.
3. Review a proposed edit or manual blocker with its schema, type, and configured runtime evidence.
4. Run your own CI and review before approving repository delivery or merging a change.

Check format and repository coverage before relying on a result. Browse the API specification tracker for the captured history, or start with a free shadow-mode report for your own authorized code.