OpenAPI diff tool — detect every change, automatically
What the diff engine detects#
10 breaking change types#
Endpoint removed · Required request field added · Response field removed · Response type changed · Enum value removed · Authentication scheme changed · Request body format changed · Path parameter renamed · Required header added · Default value changed
Non-breaking changes#
New endpoint added · Optional request field added · New response field added · Description updated · Enum value added · New optional header
CodeRifts also detects deprecations, security changes, and documentation drift.
Security changes the semver won't tell you about#
Removing an OAuth scope is a breaking change for every consumer that relied on it — their calls start returning 403 while the version number stays green. CodeRifts detects scope removals, security-scheme downgrades (OAuth2 replaced by an API key), and deleted security scheme definitions, and folds them into the risk verdict.
Why automated OpenAPI diffing matters#
Manually comparing two versions of an OpenAPI specification is tedious and error-prone. As APIs evolve, specifications can grow to thousands of lines, with complex interdependencies managed through $ref components. A simple text-based diff fails to understand the semantic meaning of the OpenAPI structure — changing a property from optional to required within a referenced schema is a significant breaking change, but it might appear as a minor, one-word alteration in a text file.
How CodeRifts performs the diff#
The engine parses both the old and new OpenAPI specifications (2.0, 3.0, or 3.1) and fully resolves all internal and external $ref pointers, creating a complete, canonical representation of each API version. It then performs a semantic comparison, categorizing every detected change as breaking, non-breaking, or deprecation, and assigns a risk score based on the type of change and its potential impact on consumers.
Three ways to diff#
- In-Browser — Upload two schemas to
app.coderifts.com/tryand get a full report instantly. No signup required. - On Every PR — Install the GitHub App and CodeRifts automatically diffs on every pull request. Zero config.
- Via API or CLI — Use the REST API or CLI to integrate diff into any CI/CD pipeline, pre-commit hook, or custom workflow.
More than a diff — a full governance report#
- Risk scoring — 0–100 score for every change.
- Policy enforcement — Custom policies to block or warn on specific breaking changes.
- Auto-changelog — Human-readable changelog from every diff.
Frequently asked questions#
Can I diff OpenAPI specs without an API key?
Yes. The in-browser tool at app.coderifts.com/try requires no signup, and the zero-auth endpoint POST /api/v1/demo returns a full diff verdict with no API key, which is useful for quick checks and for AI agents. For higher-volume or authenticated use, the REST API uses a free API key (1,000 requests per month free).
How is CodeRifts different from oasdiff or the openapi-diff CLI?
oasdiff (a Go CLI by Tufin) and the openapi-diff npm and Java tools produce a raw structural diff and a breaking or non-breaking classification, which is excellent for CI pipelines you assemble yourself. CodeRifts adds a governance layer on top of the diff: a 0 to 100 risk score, policy enforcement, OWASP-aligned security analysis, an auto-generated changelog, and zero-config delivery as a GitHub App PR comment. Use a raw diff tool if you only need the delta; use CodeRifts if you need a decision about whether the change is safe to ship.
Can an AI agent diff OpenAPI specs before acting on them?
Yes. CodeRifts serves a full diff verdict over a zero-auth endpoint (POST /api/v1/demo), and a zero-dependency coderifts_guard decorator turns that verdict into a one-line guardrail for LangGraph, AutoGen, or any Python agent. If a change would break a downstream contract, the agent halts before the unsafe call runs. Reference implementation: github.com/coderifts/example-langgraph-guard.
Can I connect CodeRifts to Claude or Cursor via MCP?
Yes. CodeRifts runs as a hosted MCP server at https://app.coderifts.com/mcp (Streamable HTTP). Add it to Claude Desktop, Cursor, or any MCP client and the agent can diff OpenAPI specs, score breaking-change risk, and get an ALLOW, WARN, REQUIRE_APPROVAL, or BLOCK decision before merging or before a tool call. See Agents for MCP.
What MCP tools does CodeRifts provide?
Exactly three: preflight_change_set, verify_receipt, get_decision_details. preflight_change_set returns the Decision Spec governance envelope (branch on execution_action). verify_receipt returns a receipt-verification result (valid, status, currently_authorized). get_decision_details returns a stored decision envelope plus retrieval metadata. The three tools do not share one response shape — an agent must branch according to which tool it called.
Can I verify a CodeRifts verdict independently?
Yes. Every verdict is signed with Ed25519 and ships with a receipt. An open-source verifier (Node and Python, github.com/coderifts/receipt-verifier) checks the signature and chain linkage against the published public key — no trust in CodeRifts required. See Portable Verification.