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, with no sign-in or account. Each change is highlighted in its operation block.
How your specs stay private
Opening a review never exposes your specs to us. The two specs and the computed comparison are encrypted with a one-time key before anything is uploaded, and only the encrypted blob is stored. The key lives in the part of the review link after the #, which browsers never send to a server, so the review is decrypted in your browser and neither oasdiff.com nor anyone with access to the stored data can read your specs.
From the CLI and the GitHub Action the encryption happens on your own machine or CI runner, so the specs never leave it in the clear. Because the key is in the link, anyone you share the full link with can open the review, so treat it like a secret. Reviews are deleted after 7 days. To skip the upload entirely, set review: false on the action.
Sharing the URL with teammates
However you created the review (with oasdiff --open from the CLI, the free GitHub Action's pull-request comment, or the diff tool's Share button), the URL (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, so treat the link like a secret. Paste it into a PR comment or your team's Slack channel and reviewers open it directly. After 7 days the URL expires; produce a fresh one by re-running the CLI, pushing a new commit to the pull request, or re-sharing from the diff tool.
Inside the review page 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 gets a review link, with no command to run. With the action's review option enabled (the default), the action posts that link as a pull-request comment so reviewers see it on the PR. It uses the workflow's built-in token automatically, so the only thing to add is permissions: pull-requests: write on the job. If it cannot comment (for example a fork pull request, where the token is read-only), the link falls back to the workflow's job summary. Either way, clicking it opens the side-by-side review directly.
The specs are encrypted in CI before upload, the same as from the CLI (see How your specs stay private). Set review: false on the action to skip the upload and add no link.
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.