API breaking changes with AI coding agents: a versioning playbook for Claude Code and Codex
A coding agent renames a field, updates every caller it can see and turns the build green. The callers it can't see, a mobile app in the store, a partner's integration, break on release. This playbook puts the contract and its consumers in the brief, gates every merge on a spec diff and gives each deprecation a date and an owner.

Your agent fixed every caller it could see. The mobile app wasn't one of them
The ticket says: store invoice amounts in cents, not as decimals. A coding agent renames the field from amount to amount_minor in the API, updates the web app, fixes the tests and opens a green merge request in fifteen minutes. The reviewer sees a clean, consistent diff and approves. The next morning, every customer still on version 3.2 of the mobile app sees an empty invoice list, because the app looks for a field that no longer exists.
The agent did exactly what it was asked. Agents are very good at making a codebase consistent, and that is the problem with APIs: the callers that matter most, installed apps, partner integrations, customer scripts, live outside the repository, where neither the agent nor the tests can see them.
The context that would have stopped it is scattered. The ticket is in Jira, the API guidelines and consumer list in Confluence, the partner contacts in Notion, the app screens in Figma, the service map on a Miro board and the deprecation email in Canva. That is six context hops for an agent and up to six AI credit meters. Our AI credit fatigue piece adds them up.
This playbook classifies every API change before it is built, writes the contract and its consumers into the brief, makes CI refuse breaking changes nobody approved, and turns every deprecation into a dated ticket with an owner.
What the API toolchain gives your agent in 2026
Breaking-change detection is mature, and the large API providers publish the rules they follow. The pieces worth knowing:
- oasdiff for OpenAPI. Compares two versions of a spec and reports what breaks existing clients. The breaking command fails CI, changelog lists everything consumers will notice, and a pre-commit hook checks changed specs. Version 1.39.0 shipped on 17 November 2026.
- Buf for Protobuf and gRPC. buf breaking compares a schema with an earlier version using rule categories from WIRE to FILE. FILE, the default, protects generated code in every language. The buf GitHub Action runs it on every pull request; a label can skip it, and an agent must never add that label.
- Pact for consumer contracts. Consumers record what they actually use, and the provider must verify every contract before it deploys. Pact's May 2026 update ships agent skills for Claude Code, Copilot and Cursor, and the SmartBear MCP server exposes contract tests and the can-i-deploy check to agents.
- Deprecation and Sunset headers. RFC 9745, a standard since March 2025, signals that an endpoint is deprecated. RFC 8594 gives the date it stops responding.
Providers show the model to copy. Stripe ships a version every month with no breaking changes and saves breaking changes for a major release twice a year; the current version is 2026-10-28.endive. GitHub released 2026-03-10, its first REST API version with breaking changes, and keeps 2022-11-28 supported until 10 March 2028. Breaking changes are allowed. Surprise isn't.
Step 1: sort every API change into a lane
The fix starts before the agent writes a line. Every ticket that touches a public or partner API gets one of four lanes, set by a person when the ticket is written:
- Additive. A new endpoint, an optional field, an optional parameter. Safe if clients ignore unknown fields. The agent can ship it after review.
- Behaviour change. Same shape, different meaning: a new default, a changed sort order, stricter validation, a different error code. No diff tool catches these, so they need a written note and a consumer check.
- Breaking. A renamed or removed field, a new required parameter, a narrower type, a changed enum. Only allowed in a new version, with the old one kept running, and approved by the API owner by name.
- Removal. Turning off an old version or endpoint. Only after the sunset date, with traffic on it near zero, and as its own ticket.
Agents misjudge lanes in a predictable way: they call a rename a refactor. Make the lane a field on the ticket, let the agent suggest raising it, and let only a person lower it.
Step 2: the seven-field API change brief
For anything above Additive, add these seven fields next to the acceptance criteria.:
- 1. Contract. The spec file that is the source of truth: the OpenAPI document, the proto package or the GraphQL schema. The agent changes the contract first, then the code.
- 2. Consumers. Who calls this, from where, and which old versions are still in use: the web app, mobile app versions in the store, named partners, public SDKs.
- 3. Lane and reason. The lane from step 1, and why the change can't be additive.
- 4. Compatibility plan. Usually expand and contract: add the new field next to the old one, write both, move consumers, then remove the old one in a later ticket. Or a new version, with the old one kept as it is.
- 5. Deprecation plan. The Deprecation and Sunset dates, the changelog entry, who tells the partners and how.
- 6. Proof. The spec diff output, consumer contract tests passing, and a test that calls the old shape and still gets the old answer.
- 7. Owner. The person who approves the break and owns the sunset date, by name.
Field 2 does most of the work. An agent can only protect callers it knows about, and the list rarely lives in the repository. Field 6 turns compatibility from advice into tests. Our acceptance criteria guide explains how to write criteria an agent can't pass by accident.
Step 3: make CI refuse breaking changes nobody approved
The brief tells the agent what to do. CI makes sure it did. Three gates, each one the agent can run itself before it opens the merge request:
- Spec diff against main. oasdiff breaking or buf breaking compares the contract on the branch with the one on main and fails on anything breaking. The approved exceptions live in a file a person edits, not the agent.
- Consumer contracts. Pact verifies the provider against every consumer contract, and can-i-deploy blocks a release that would break a version still in production.
- Old-shape tests. A small set of tests pinned to the previous version's requests and responses. They must still pass.
Three guardrails keep the gates honest. The agent never edits the baseline spec on main, the list of accepted breaking changes or the CI file. It never adds the skip label. And when a gate fails, it stops and reports instead of rewriting the test until it passes. The four-pass review checklist covers the human read that follows.
Where API context lives in 2026, and what it costs
An API change needs the ticket, the guidelines, the consumer list, the screens and the service map. Before any contract tool, that is usually six subscriptions:
| Tool and plan | Seat / month | AI layer and limits | API context usually kept there |
|---|---|---|---|
| Jira Standard | $9.70 | Rovo, 25 credits per user per month on Standard (70 Premium, 150 Enterprise), $0.01 per extra credit from 3 Dec 2026 | The ticket and the breaking-change label |
| Confluence Standard | $7.15 | Same pooled Rovo credits | API guidelines, versioning policy |
| Notion Plus | $12.00 | Custom Agents on credits, Business and Enterprise only | Partner list and contacts |
| Figma Professional, Full seat | $20.00 | 3,000 AI credits per Full seat per month; MCP reads 200 per day on Full and Dev | Client screens that read the field |
| Miro Starter | $10.00 | Create with AI on Miro credits | Service and consumer map |
| Canva Business | $25.00 | Canva AI usage per member | Deprecation emails and notices |
| Six-tool total | $83.85 | Up to six meters, six MCP servers | One change, six places |
| Sydla | $19.00 | None: your own Claude Code or Codex plan pays for the model | Brief, consumers, states, run, spec diff and sign-off on one work item |
Your contract tools stay: Sydla does not replace oasdiff, Buf or Pact. It replaces the six places an agent and a reviewer have to rebuild the consumer list from. The comparison overview covers each tool, and the pricing section lists the source for every price.
Keep the contract and its consumers where the agent works, without a second AI bill
Keep the brief, the consumer list, the client states, the agent run, the spec diff and the owner's sign-off on one work item, and let your own coding agent read them through one connection, for $19 per month instead of $83.85. That is $64.85 saved per user, every month, with no credit meter running while the agent changes the contract, checks it and fixes it.
Step 4: when you are the consumer, upgrade one major at a time
Agents are just as useful upgrading your code to someone else's new version. The rules are the mirror image:
- Pin the version. Send the version header on every request, Stripe-Version or X-GitHub-Api-Version, instead of trusting the account default. Unversioned GitHub requests still get 2022-11-28, and that version closes on 10 March 2028.
- One major per ticket. The agent reads that release's changelog and maps each breaking change to a file.
- Test with the header first. Stripe's own upgrade-stripe agent skill tells agents to try the new version on test requests before changing the pinned version in code.
- Watch for 410 and Sunset. Log Deprecation and Sunset headers from your providers and turn each one into a dated ticket.
SDK upgrades follow the same loop. Our dependency upgrade guide covers the rest.
Step 5: deprecate on a date, remove in a separate ticket
Most API breakages aren't bad changes. They are removals that came too early or too quietly. Give every deprecation a calendar:
- Announce in the response. The old field or version returns a Deprecation header and a Sunset date. The agent adds both as part of the expand ticket.
- Measure who still calls it. Log every call to the deprecated shape by client and app version, so the owner knows when traffic is near zero and who to email.
- Write the removal ticket now, schedule it later. The contract step gets its own work item, its own owner and the sunset date as a start condition. Without it, the old field lives forever.
- Remove only on evidence. On the date, the agent checks traffic, removes the old shape, the spec diff shows the expected break, and the owner approves it.
Database columns follow the same expand, migrate and contract rhythm. Our database migrations guide covers it from the schema side.
Walkthrough: brief, UX Studio, your agent in Sydla Desktop, review
Here is how a breaking API change moves through Sydla on one work item, with the coding agent you already pay for.
- Brief on the work item. The ticket in Sydla carries the lane, the acceptance criteria and the seven API fields, written once and read by every agent and person.
- States in UX Studio. API changes have screens too: the new shape, an old app version, the upgrade notice. Our design handoff guide explains why states beat screenshots.
- Run in Sydla Desktop with your own agent. Sydla Desktop launches the Claude Code or Codex CLI on your machine, signed in with your own Anthropic or OpenAI account. The agent reads the work item through the Sydla MCP server, changes the contract, keeps the old shape, runs the spec diff and attaches the output. There are no Sydla AI credits and no token markup. The Desktop guide walks through the first run.
- Review and sign-off. CI gates run, a fresh read-only session checks the old-shape tests and the consumer list, and the API owner approves on the work item before the merge. The removal ticket is created with the sunset date.
Agents change the contract and prove compatibility. Tools catch the break. People own the consumers and the date.
A filled-in example: invoice amounts in minor units
Here is a condensed API change brief. The service, versions and figures are illustrative:
- Lane: Breaking. The invoice amount moves from a decimal in euros to an integer in cents, to stop rounding errors.
- Contract: the invoices OpenAPI spec, the Invoice schema.
- Consumers: the web app; mobile app 3.2 and later, with about 18% of users still on 3.2; two partners that pull invoices nightly.
- Compatibility plan: add amount_minor and currency next to amount, return both, move the web and mobile apps, keep amount until the sunset date.
- Deprecation plan: amount is marked deprecated in the spec; responses carry a Deprecation header now and a Sunset date six months out; the owner emails both partners.
- Proof: the spec diff shows additions only; old-shape tests for amount still pass; the partners' Pact contracts verify.
- Owner: the billing API lead approves and owns the sunset date.
In this example the agent's first run does what the agent in the opening did: it renames the field. The spec diff fails on the removed property before anyone reviews it. The agent puts amount back and writes both fields. The old-shape tests then catch something nobody wrote down: amount used to be rounded to two decimals and now wasn't, a behaviour change in a field that hadn't changed. One more fix, and the removal ticket goes into the plan. The bug report template shows how to brief a break that slips through anyway.
Frequently asked questions
What counts as a breaking API change?
Any change that can make an existing client fail without changing its code: removing or renaming a field, endpoint or parameter, making an optional parameter required, narrowing a type, changing an enum, or changing what a response means. Adding optional fields and new endpoints is usually safe, as long as clients ignore fields they don't know.
How do you stop an AI coding agent from breaking an API?
Write the contract and its consumers into the ticket, sort the change into additive, behaviour change, breaking or removal, and gate every merge on a spec diff such as oasdiff breaking or buf breaking, plus consumer contract tests. The agent must not edit the baseline spec or skip the check, and a named API owner approves every breaking change.
What are the Deprecation and Sunset HTTP headers?
The Deprecation header, standardised in RFC 9745 in March 2025, tells clients that a resource is or will be deprecated. The Sunset header, from RFC 8594, gives the date the resource is expected to stop responding. GitHub uses them in its REST API, and closed versions return 410 Gone.
How do Stripe and GitHub version their APIs?
Stripe releases a new API version every month with no breaking changes and a major release with breaking changes twice a year; the current version is 2026-10-28.endive. GitHub uses dated versions sent in the X-GitHub-Api-Version header; 2026-03-10 was its first version with breaking changes, and 2022-11-28 stays supported until 10 March 2028.
How much does Sydla cost compared with Jira, Confluence, Notion, Figma, Miro and Canva?
Sydla costs $19 per user per month. One paid seat each of Jira Standard, Confluence Standard, Notion Plus, Figma Professional Full, Miro Starter and Canva Business costs $83.85 per user per month, so the saving is $64.85 per user per month. You bring your own Claude Code or Codex account, so your Anthropic or OpenAI plan pays for the model with no markup.





























