CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

breakra

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.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./SKILL.md
SKILL.md
Quality
Evals
Security

Breakra: contract-safety check for agents

Breakra 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/.

When to use it

  • Before merging or releasing a change to an OpenAPI contract: "does this PR break clients?"
  • When upgrading to a new version of a third-party API: "what changed that affects my integration?"
  • When writing release notes or a migration guide: you get a list of changes with reasons and actions, and a suggested semver bump.

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.

Request

{ "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}).
  • Local $refs (#/…) are resolved, including circular ones. External $refs are never fetched: they're listed in limitations. Inline them first if they matter.
  • Limits: 1 MB body (1,048,576 bytes for the whole JSON request), nesting 64, 5,000 operations, 75,000 nodes once $refs are expanded. Over a limit → a free 413 or 422.

Paying (x402)

  1. 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.

  2. Check the terms before signing. Refuse anything that differs:

    FieldExpected
    x402Version2
    schemeexact
    networkeip155:8453 (Base)
    assetUSDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
    amount20000 or less (USDC has 6 decimals, so $0.02)
    payTo0x8AEE621035D93Deb3C0C1177fac252dC2dd501a0 (Bankr's fee router, which forwards to the service owner in the same transaction)
    maxTimeoutSeconds60 or less (how long your signature stays valid)
    extra.assetTransferMethodabsent or eip3009 (a USDC TransferWithAuthorization, not Permit2)
  3. 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:

  • One signature per call. Don't let a client library re-sign and resend automatically: if the first paid attempt succeeded, a second signature is a second charge. A reused signature gets 402 Payment already used.
  • No payment receipt header is returned. A 200 with Breakra's JSON result means you paid. Not charged only when the response is Breakra's own JSON error ({"status":"error","error":{"code":…}}, one of the codes below) or an x402 402.
  • Anything else is an unknown outcome, not a free error: a gateway 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.
  • Retrying after one of Breakra's own errors is safe and free. Only 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 whole call takes about 3–20 s depending on size (a 940 KB pair took 18 s end to end). Use a timeout of at least 30 s, and the direct Bankr URL for bodies over 500 KB.

A reference client that checks every term above, signs once and treats ambiguous failures as unknown: examples/client.ts.

Reading the result

{
  "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, "…": "…" }
}
compatibilityMeaningWhat to do
breakingExisting callers will fail (a removed operation)Block the release, or ship as a new major version with a migration path
potentially_breakingSome callers may fail, depending on how they use itReview each finding. Request side: callers' current inputs may be rejected. Response side: callers may get values they don't handle
unknownChanged in a way the rules don't evaluateReview by hand. Never treat as safe
compatibleAdditive; well-behaved callers are unaffectedNothing required
non_contractDocs or metadata onlyNothing required
  • Act on 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.
  • The top-level 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.
  • Always read limitations (an array of plain-English strings). A result with external $refs didn't see what those refs point to.
  • Rules are versioned (rule_set_version). The full rule table is in RULES.md.

Errors (never charged)

HTTPerror.codeFix
400INVALID_REQUESTSend JSON with before and after (each an object or JSON/YAML text) and optionally uses
405METHOD_NOT_ALLOWEDUse POST
413PAYLOAD_TOO_LARGEBody over 1 MB: drop unrelated paths from both contracts and compare in parts
422INVALID_SPECIFICATIONMissing openapi/info/paths, a malformed path or operation, or a $ref that doesn't resolve
422UNSUPPORTED_OPENAPI_VERSIONOnly OpenAPI 3.0.0–3.0.4 and 3.1.0–3.1.1 are supported (no Swagger 2.0)
422SPEC_TOO_COMPLEXToo deep, too many operations, or $refs expand too far: compare a subset of paths
500ANALYSIS_FAILEDUnexpected; retry once with the same input

Error bodies look like {"status":"error","error":{"code":"…","message":"…","retryable":false}} and never echo your input.

Privacy

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.

Repository

danbuildss/breakra

Path

SKILL.md

Last updated
First committed

Also appears in

danbuildss/breakra
In sync

since Nov 16, 2026

Is this your skill?

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.