Repository avatar
Other Tools
v0.2.2
active

breakra

io.github.danbuildss/breakra

OpenAPI 3.0/3.1 breaking-change checks for agents: safe/review/block verdict, evidence, fixes.

Documentation

Breakra: know what changed before your integration breaks. OpenAPI 3.0/3.1 compatibility checks for coding agents: free locally, or $0.02 USDC on Base via x402.

breakra.dev  Star Breakra on GitHub  Agent guide (SKILL.md)  Real example: GitHub REST API  API docs  Contribute

Breakra compares two OpenAPI 3.0/3.1 contracts (JSON or YAML) and tells a coding agent what may break for its callers, or for the operations it depends on: a verdict, every change classified, the evidence and a recommended fix.
Free locally, or one HTTP call at $0.02 USDC on Base via x402. Breakra's own errors are never charged.

🤖 Using a coding agent? Point it here: read https://breakra.dev/skill.md and follow it to check an OpenAPI change.

CI license price x402 engine OpenAPI


Vision

Breakra is the contract-safety check for AI agents. Before an agent changes an API, or upgrades to someone else's, Breakra tells it whether the change may break your callers or the operations you depend on, with evidence, a clear verdict and a recommended fix. It is deterministic and verifiable, free to run locally, and pay-per-use with no account when hosted. Read the full vision and roadmap in VISION.md.

How it works

Send the old and new contract, pay $0.02 once, get every change classified with evidence and a fix.

Send the old and the new contract. Breakra validates both, diffs them, and classifies every change by who it affects (request or response side) and how (narrowing, widening, removal). The same inputs always give the same analysis_id and the same findings, so a result can be kept with the change that caused it.

Quick start

Endpoint: POST https://x402.bankr.bot/0xb98f0de777eea8c481b64e33d3e0066cea38fa91/breakra-analyze

{ "before": { "openapi": "3.0.3", "…": "…" }, "after": { "openapi": "3.0.3", "…": "…" } }
Free and local: CLI or MCP server (no wallet)

Same engine, on your machine, nothing sent anywhere. Needs Node.js 20+ (npm package, no dependencies).

npx -y breakra check old.yaml new.yaml                                    # verdict, findings, fixes
npx -y breakra check old.yaml new.yaml --use "GET /orders/{id}" --fail-on review   # only the operations you call
claude mcp add --scope user breakra -- npx -y breakra mcp                 # MCP tool: check_openapi_change

Pin a version in CI or agent configs (npx -y breakra@0.2.2 …). From source instead: git clone --branch v0.2.2 --depth 1 https://github.com/danbuildss/breakra && cd breakra && bun install && bun src/cli.ts check old.yaml new.yaml.

Exit codes: 0 below --fail-on (default block), 1 at or above it, 2 error. --json prints the hosted API's exact result.

With a coding agent

Give your agent SKILL.md. It covers when to call Breakra, the exact payment terms to check before signing, and how to act on each finding.

With the TypeScript client
git clone https://github.com/danbuildss/breakra && cd breakra && bun install
BREAKRA_KEY_FILE=./wallet.key bun examples/client.ts old.json new.json

examples/client.ts checks the terms before signing (exact, Base, USDC, at most $0.02), signs once and never re-sends with a new payment. Use a dedicated low-balance wallet.

With curl (see the payment terms)
curl -i -X POST -H 'content-type: application/json' --data @examples/request.json \
  https://x402.bankr.bot/0xb98f0de777eea8c481b64e33d3e0066cea38fa91/breakra-analyze
# → 402 with the x402 terms in the payment-required header. Paying needs an x402 client.

A real example

GitHub REST API description, Dec 2025 to Oct 2026: 5 breaking, 35 potentially breaking, 10 compatible, 9 docs-only changes.

Six paths of GitHub's published REST API description, Dec 2025 → Oct 2026: team discussions, tag protection and Copilot org metrics are gone from the contract; the issue timeline gained 13 event types; billing budget fields were dropped from PATCH. Inputs, full output and write-up: demo/github-rest-api/.

What each finding means

compatibilityMeaningWhat to do
breakingExisting callers will fail (a removed operation)Block the release, or ship a new major version
potentially_breakingSome callers may fail: a new required input, a removed or now-optional response field, a new enum value…Review each finding
unknownChanged in a way the rules don't evaluateReview by hand; never treat as safe
compatibleAdditive; well-behaved callers are unaffectedNothing
non_contractDocumentation or metadata onlyNothing

Each finding carries a stable rule id, the operation, a location (parameter, status, media type, field), evidence (before/after values), a reason and a recommended_action. Full rule table: RULES.md. Response schema: openapi.json.

How payment works

The first request returns 402 with the terms; the agent checks them and signs once; the paid request returns 200 and is charged $0.02; a Breakra error is never charged; a gateway failure is an unknown outcome.

  • Paid with x402 on Base: exact scheme, USDC, 20000 ($0.02), to Bankr's fee router. Hosted on Bankr x402 Cloud.
  • Only a 200 is charged. Breakra's own errors (invalid input, oversize specs, a JSON error.code) are never charged.
  • A gateway error, timeout or reset is an unknown outcome, not a free error: don't re-sign; wait 60 s and check your wallet's transfers first.
  • Sign once per call. A reused signature is rejected; a new signature is a new charge.

Limits and privacy

  • OpenAPI 3.0.0–3.0.4 and 3.1.0–3.1.1, as JSON objects or JSON/YAML text, inline. Not supported: Swagger 2.0, OpenAPI 3.2, URL inputs.
  • Request body ≤ 1 MB; nesting, operation and $ref-expansion limits apply. Over a limit → a free 413 or 422.
  • For bodies over 500 KB, use the direct Bankr URL above rather than breakra.dev/api/analyze: the forward adds a hop with its own proxy timeout.
  • External $refs are never fetched; they're listed in limitations.
  • Submitted contracts are not stored or logged. Logs hold only outcome, size, change count, duration and the paying address.

Docs

breakra.devWebsite; agents can fetch /skill.md and /openapi.json there
VISION.mdWhere Breakra is going, and how we'll judge it
CHANGELOG.mdWhat changed in each release
benchmark/Benchmark on real API history (GitHub, Stripe) and curated scenarios: how often it blocks, hand-checked findings, known limits
SKILL.mdAgent guide: when to call, payment terms, reading results
docs/API.mdRequest, response and error reference
openapi.jsonMachine-readable contract of the endpoint
RULES.mdEvery classification rule (rule set 0.2.0)
examples/Sample request and response, paying client, curl, GitHub Actions workflow
demo/github-rest-api/Real-world run on GitHub's API description
SECURITY.mdReporting vulnerabilities privately

Development

Requires Bun ≥ 1.4.2.

bun install --frozen-lockfile
bun run check      # typecheck, lint, tests, build, smoke test of the built handler
bun run oracle     # cross-check against oasdiff v1.33.0 (also runs in CI)
PathWhat
src/core/validate.tsValidation and resource limits
src/core/compare.tsRaw diff via api-smart-diff
src/core/classify.tsThe rules
src/index.tsThe HTTP handler, built into one file for Bankr (bun run build)
tests/Rule, validation, handler, docs-drift and metrics tests

Releases and deployment: docs/DEPLOYMENT.md. Project history and decisions live in docs/project/.

We love contributors

The most useful contribution is a wrong finding: a change Breakra misclassified or missed. Open one with the Report a wrong finding template, with a minimal before/after pair. New rules, fixes and docs are welcome too: start with CONTRIBUTING.md.

License

MIT. The built handler bundles api-smart-diff (MIT).

NPM
breakra
Install Command
npm install breakra
Runtime: npx