Help Centre — Apibreak

Getting Started

Apibreak compares two OpenAPI or Swagger specifications and classifies every difference as BREAKING, ADDITIVE, or COSMETIC.

Open the app

Go to apibreak.agen2ic.ai/app. No account, no sign-up, no data sent to any server.

Paste or upload two specs

Paste the content of your old spec (Spec A — "yesterday") into the left panel and your new spec (Spec B — "today") into the right panel. Accepts JSON and YAML, OpenAPI 3.x and Swagger 2.0.

Click Compare or press Ctrl+Enter

The engine diffs the specs structurally — not textually — and groups every difference into the three buckets. Breaking changes are shown first because those are the ones you care about most.

Read the report, export if needed

Each breaking change shows the path, what changed, what a client that relied on the old behaviour will see, and the before/after values. Use Export JSON or Export Markdown to share the report with your team.

Frequently Asked Questions

What formats and spec versions does Apibreak accept?

Apibreak accepts JSON and YAML, for both OpenAPI 3.x (3.0, 3.1) and Swagger 2.0. Paste raw text or upload a file. If a document is not a parseable spec, the tool will tell you plainly rather than guessing.

Are my specs uploaded to a server? Is this safe for proprietary APIs?

Everything runs locally in your browser. No spec data, no personal information, and no usage metrics are sent to any server. There is no database, no analytics, and no backend. Refreshing or closing the page clears all spec content from memory. This makes Apibreak safe for internal/proprietary APIs — your spec never leaves your machine.

What do the three bucket labels mean?

BREAKING — An existing client will stop working. A removed endpoint, a deleted response field, a required parameter added, a type changed from string to enum, a status code removed. Shows before/after values and what a relying client will experience.

ADDITIVE — New surface that existing clients are not affected by. A new endpoint, an optional parameter added, a new response header. Safe to deploy without coordination.

COSMETIC — Descriptions, examples, ordering, formatting. Counted, not individually listed, so the report stays short enough to read.

Apibreak says "not a valid spec" — what's wrong?

The tool tries to parse your input as an OpenAPI or Swagger document. Common issues: missing openapi or swagger key at the root, invalid JSON (check trailing commas), invalid YAML (check indentation), or a document that is valid YAML/JSON but not an API specification. The error message will say which side (Spec A or Spec B) failed and why. Use the Load Example fixture buttons to verify the tool works with known-good specs, then compare your document structure.

How do I use the Pro features?

Pro features (batch comparison, collapsible diff trees, larger exports) are available via the checkout form on the pricing page. Pro is billed at $12/month, billed annually ($144/year). The checkout is connected to Stripe in test mode — no real payment is taken during the demo period. For billing questions, email apibreak@agen2ic.ai.

The tool gave an unexpected classification — is it wrong?

The classification engine is a best-effort structural analysis and is not infallible. Edge cases — particularly around OpenAPI 3.1 JSON Schema keyword changes, oneOf/anyOf composition changes, and custom extensions — can sometimes produce unexpected results. The report is not a substitute for human review. If you believe a classification is incorrect, email us with the two specs (or a minimal reproduction) at apibreak@agen2ic.ai and we will investigate.

Known Limitations

Apibreak is a client-side tool with a deliberately narrow scope. The following are not bugs — they are design boundaries:

No URL fetching. Apibreak cannot fetch a spec from a URL, a repository (GitHub, GitLab), or a package registry. You must paste or upload the file content.
No storage or persistence. Spec content exists only in browser memory. Reloading the page clears everything. The Pro tier mentions a "comparison history" feature — that is not yet implemented.
No CI integration. Apibreak does not offer a CLI, a GitHub Action, a webhook, or any programmatic API. It is a browser-based analysis tool only.
No judgment. Apibreak tells you what is breaking; it does not decide whether the break is justified or acceptable. That decision belongs to your team.
Best-effort classification. Edge cases around 3.1 JSON Schema keywords, composition keywords (oneOf/anyOf), and custom extensions may produce unexpected results. Always review the report before acting on it.
No multi-file specs. OpenAPI documents that use $ref to reference external files are not supported — the spec must be fully self-contained in a single file.
No email delivery. There is no email sender. Comparison results cannot be emailed from the tool — use Export JSON or Export Markdown to share reports.
Mock payment processing. The checkout on the pricing page uses Stripe test-mode keys. No real payment is processed. Pro features are not yet available; the pricing page is a demonstration of intent.

Contact Us

For questions, bug reports, feature requests, or billing inquiries — we read every message.

Email us at:

apibreak@agen2ic.ai

Please include the product name "Apibreak" in your subject line so we can route your message quickly.

How to use Apibreak, answered.