Check whether an OpenAPI 3.0/3.1 change (JSON or YAML) may break API consumers, or the operations you depend on. Send the old and new contract; get a verdict (safe/review/block), a semver bump, and every change classified with evidence and a recommended fix. Free locally (CLI/MCP), or hosted at $0.02 USDC on Base via x402.
80%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./SKILL.mdBreakra compares two OpenAPI 3.0/3.1 contracts (JSON or YAML) and tells you whether the change is safe, needs review, or should be blocked. It also lists which changes may break callers (or, with uses, you), where they are, and what to do about them. Results are deterministic: the same inputs always give the same analysis_id and the same findings.
Two ways to run it:
Free and local (no wallet, nothing leaves your machine): bun src/cli.ts check before.yaml after.yaml from a clone of the repo, or add the MCP server: claude mcp add breakra -- bun /path/to/breakra/src/cli.ts mcp (tool: check_openapi_change). Needs Bun.
Hosted (nothing to install, pay per call): the endpoint below.
Endpoint: POST https://x402.bankr.bot/0xb98f0de777eea8c481b64e33d3e0066cea38fa91/breakra-analyze (also POST https://breakra.dev/api/analyze, which forwards to it: same terms, same result). For a request body over 500 KB, call the Bankr URL directly: the breakra.dev forward adds a network hop with its own proxy timeout, so a slow large call could be cut off after Bankr has already charged it.
Price: $0.02 USDC on Base (x402 v2, scheme exact, network eip155:8453, amount 20000). Only a 200 is charged. Every error (4xx/5xx) is free.
Contract: openapi.json. Example request and response: examples/.
Don't use it for: Swagger 2.0, OpenAPI 3.2, contracts given only as URLs (fetch them yourself), or a combined request body over 1 MB.
{ "before": { "openapi": "3.0.3", "info": { "title": "…", "version": "1" }, "paths": { } },
"after": "openapi: 3.1.0\ninfo:\n title: …\n version: '2'\npaths: {}\n",
"uses": [{ "method": "GET", "path": "/orders/{id}" }] }before and after: each a whole inline OpenAPI 3.0.0–3.0.4 or 3.1.0–3.1.1 document, as a JSON object or as JSON/YAML text (a string).uses (optional): the operations your code calls. The result then has an impact section: a verdict for those operations and the ids of the findings that touch them. This is usage-based filtering of contract changes: Breakra doesn't read your code, so it can't prove how your code behaves. Path parameter names don't need to match (/orders/{id} = /orders/{orderId}).$refs (#/…) are resolved, including circular ones. External $refs are never fetched: they're listed in limitations. Inline them first if they matter.$refs are expanded. Over a limit → a free 413 or 422.POST the body with no payment. You get 402 with the terms in the payment-required header (base64 JSON). The 402 comes before your body is validated, so a bad request is only rejected (free) on the paid attempt.
Check the terms before signing. Refuse anything that differs:
| Field | Expected |
|---|---|
x402Version | 2 |
scheme | exact |
network | eip155:8453 (Base) |
asset | USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
amount | 20000 or less (USDC has 6 decimals, so $0.02) |
payTo | 0x8AEE621035D93Deb3C0C1177fac252dC2dd501a0 (Bankr's fee router, which forwards to the service owner in the same transaction) |
maxTimeoutSeconds | 60 or less (how long your signature stays valid) |
extra.assetTransferMethod | absent or eip3009 (a USDC TransferWithAuthorization, not Permit2) |
Sign one EIP-3009 USDC authorization and resend the same body with the PAYMENT-SIGNATURE header. With @x402/core + @x402/evm, call x402HTTPClient.getPaymentRequiredResponse, createPaymentPayload and encodePaymentSignatureHeader yourself. Don't use wrapFetchWithPayment, which can re-sign and resend on its own.
Rules:
402 Payment already used.{"status":"error","error":{"code":…}}, one of the codes below) or an x402 402.502/503/504, an HTML or plain-text body, a timeout or a reset. A proxy (such as the breakra.dev forward) can fail after Bankr has already charged. Don't re-sign: wait at least 60 s (the signature then expires and can't settle any more) and check your wallet's USDC transfers to payTo before trying again.ANALYSIS_FAILED (500) is worth retrying with the same input; other errors will repeat. A retry starts over: unpaid request, new 402, new signature (the old signature can't be reused).A reference client that checks every term above, signs once and treats ambiguous failures as unknown: examples/client.ts.
{
"status": "success",
"analysis_id": "sha256:…",
"compatibility": "breaking",
"verdict": "block",
"suggested_version_bump": "major",
"summary": { "total_changes": 15, "breaking": 1, "potentially_breaking": 10, "unknown": 0, "compatible": 2, "non_contract": 2 },
"changes": [
{
"id": "change-002",
"rule": "request.required_parameter_added",
"compatibility": "potentially_breaking",
"direction": "request",
"operation": { "method": "GET", "path": "/orders" },
"location": { "in": "query", "name": "customer_id" },
"reason": "A new required query parameter `customer_id` was added to GET /orders. Callers that do not send it may be rejected.",
"recommended_action": "Update callers of GET /orders to send `customer_id`.",
"evidence": { "path": ["paths", "/orders", "get", "parameters", "query:customer_id"], "before": null, "after": { "…": "…" } }
}
],
"limitations": [],
"metadata": { "changes_omitted": 0, "…": "…" }
}compatibility | Meaning | What to do |
|---|---|---|
breaking | Existing callers will fail (a removed operation) | Block the release, or ship as a new major version with a migration path |
potentially_breaking | Some callers may fail, depending on how they use it | Review each finding. Request side: callers' current inputs may be rejected. Response side: callers may get values they don't handle |
unknown | Changed in a way the rules don't evaluate | Review by hand. Never treat as safe |
compatible | Additive; well-behaved callers are unaffected | Nothing required |
non_contract | Docs or metadata only | Nothing required |
verdict: block = breaking changes (don't ship, or ship as a new major version); review = potentially breaking or unknown changes (check each one); safe = nothing that may break callers. With uses, act on impact.verdict instead: it covers only your operations plus document-wide changes.suggested_version_bump is semver advice for the API's own version: major for anything that may break callers (or that the rules can't evaluate), minor for additive changes, patch for docs only.compatibility is the most severe class found.direction says who is affected: request (what callers send), response (what callers receive), operation, security or document.changes is sorted most severe first and capped at 500. summary always counts everything; metadata.changes_omitted says how many weren't listed.limitations (an array of plain-English strings). A result with external $refs didn't see what those refs point to.rule_set_version). The full rule table is in RULES.md.| HTTP | error.code | Fix |
|---|---|---|
| 400 | INVALID_REQUEST | Send JSON with before and after (each an object or JSON/YAML text) and optionally uses |
| 405 | METHOD_NOT_ALLOWED | Use POST |
| 413 | PAYLOAD_TOO_LARGE | Body over 1 MB: drop unrelated paths from both contracts and compare in parts |
| 422 | INVALID_SPECIFICATION | Missing openapi/info/paths, a malformed path or operation, or a $ref that doesn't resolve |
| 422 | UNSUPPORTED_OPENAPI_VERSION | Only OpenAPI 3.0.0–3.0.4 and 3.1.0–3.1.1 are supported (no Swagger 2.0) |
| 422 | SPEC_TOO_COMPLEX | Too deep, too many operations, or $refs expand too far: compare a subset of paths |
| 500 | ANALYSIS_FAILED | Unexpected; retry once with the same input |
Error bodies look like {"status":"error","error":{"code":"…","message":"…","retryable":false}} and never echo your input.
Breakra's code does not store or log submitted contracts. Its logs hold only the outcome, size, change count, duration and the paying address. Requests pass through Bankr x402 Cloud (the host); don't send contracts you aren't allowed to share with a third-party service.
danbuildss/breakra
SKILL.md
099ee23
Also appears in
since Nov 16, 2026
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.