Skip to main content
Glama

πŸ€– 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.

Related MCP server: SpecShield MCP Server

How it works

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", "…": "…" } }

Same engine, on your machine, nothing sent anywhere. Needs Bun.

git clone https://github.com/danbuildss/breakra && cd breakra && bun install
bun src/cli.ts check old.yaml new.yaml                     # verdict, findings, fixes
bun src/cli.ts check old.yaml new.yaml --use "GET /orders/{id}" --fail-on review   # does it break me?
claude mcp add breakra -- bun "$PWD/src/cli.ts" mcp        # MCP tool: check_openapi_change

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

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.

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.

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

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

compatibility

Meaning

What to do

breaking

Existing callers will fail (a removed operation)

Block the release, or ship a new major version

potentially_breaking

Some callers may fail: a new required input, a removed or now-optional response field, a new enum value…

Review each finding

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

non_contract

Documentation or metadata only

Nothing

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

  • 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. Invalid input, oversize specs and errors return 4xx/5xx and are free.

  • 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.dev

Website; agents can fetch /skill.md and /openapi.json there

VISION.md

Where Breakra is going, and how we'll judge it

CHANGELOG.md

What changed in each release

SKILL.md

Agent guide: when to call, payment terms, reading results

docs/API.md

Request, response and error reference

openapi.json

Machine-readable contract of the endpoint

RULES.md

Every classification rule (rule set 0.1.0)

examples/

Sample request and response, paying client, curl

demo/github-rest-api/

Real-world run on GitHub's API description

SECURITY.md

Reporting 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)

Path

What

src/core/validate.ts

Validation and resource limits

src/core/compare.ts

Raw diff via api-smart-diff

src/core/classify.ts

The rules

src/index.ts

The 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).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Signed, offline-verifiable authorization for API-contract changes. Before a contract change (OpenAPI, GraphQL, Protobuf, AsyncAPI, MCP manifests) merges or deploys, the agent calls preflight_change_set; the decision is deterministic, signed, and verifiable without calling CodeRifts. Three tools: preflight_change_set, verify_receipt, get_decision_details. Only a granted change can proceed.
      2 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A read-only API change deploy gate for AI coding agents that analyzes OpenAPI specs to determine if changes are safe to deploy. It provides tools for comparing specs, explaining breaking changes, and generating migration guides.
      5
      51 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that watches upstream API providers for breaking changes, scans your codebase for impact, and drafts migration fixes locally, all offline-first with zero network.
      80 npm
      1
      AGPL 3.0