Free API Change Review
The oasdiff CLI can upload two OpenAPI specs to oasdiff.com and open a side-by-side review URL you can share with your team. Add --open to oasdiff changelog (or oasdiff breaking) and the CLI handles the upload and browser launch.
Want every reviewer on a PR to approve or reject each change, with a commit-status merge gate and an audit trail? See oasdiff Pro setup.
Quick start
- Install oasdiff (one-time per machine):
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | shSee the install guide for Homebrew, Docker, and Go-install alternatives.
- Run the CLI in your repo, pointing at the two versions of your spec you want to compare:
oasdiff changelog HEAD~1:openapi.yaml HEAD:openapi.yaml --openBoth arguments accept file paths, URLs, git refs (
<sha>:<path>or<branch>:<path>), or stdin — same as any other oasdiff command. - See the side-by-side review. The CLI prints the changelog in your terminal and opens the rendered review at
oasdiff.com/review/e/[id]in your browser. No sign-in or account: the two specs are encrypted on your machine before upload and the key stays in the URL fragment, so oasdiff.com stores a blob it can't read. Each change is highlighted in its operation block.
Sharing the URL with teammates
The URL the CLI prints (e.g. oasdiff.com/review/e/4b8e-12fc-...#k=...) is unguessable and works for 7 days. The part after the # is the decryption key, so anyone you give the full link to can open the review — share it like a secret. Paste it into your PR comment or your team's Slack channel and reviewers open it directly, with no CLI install and no account on their side. After 7 days the URL expires; re-run the CLI to generate a fresh one.
You can also share a single change. Each change in the review has a Copy link to this change button that copies a link opening the review scrolled straight to that change, so you can point a teammate at one specific change instead of the whole diff. The decryption key is preserved in the link, so it opens just like the full review URL.
From a GitHub Action review link
If your repo has the free oasdiff GitHub Action installed, every pull request with API changes adds a link to the workflow's Step Summary. With the action's review option enabled (the default), that link opens the side-by-side review directly: click it and you see exactly what changed, with no command to run.
The two specs are encrypted in CI before they are uploaded, and the decryption key stays in the part of the link after the #, which browsers never send to a server, so the review renders without our servers being able to read your specs. If you set review: false on the action, it skips the upload and adds no link; run the CLI quick start above whenever you want a review.
Pro vs free, on this one workflow
The free review is read-only: reviewers can see and share the changes side by side, but the approve / reject buttons are locked and nothing is recorded. For teams that need to sign off on changes before they ship, oasdiff Pro posts a rich PR comment with the same side-by-side review pre-rendered, the approve / reject buttons work, and a commit status check updates the merge gate, with an audit trail of who approved what.