ApiNotes Sentinel captures real HTTP traffic from your test suite and automatically patches your OpenAPI spec to match. No more specs that lie. No more drift. No more manual diffs.
Free open-source CLI · Optional cloud platform for teams · Works with GitHub & GitLab CI
No spam. Unsubscribe any time.
Consumers get surprised
A field your spec promised no longer exists. Integrations break in production.
Manual sync is expensive
Developers spend hours cross-referencing logs, code and spec files by hand.
Breaking changes slip through
No one catches that a required field was added or a response schema changed.
Run your existing test suite. The CLI does the rest — no code changes required.
Point Sentinel at your existing tests. It starts a local proxy, injects the URL into your test runner, and records every request and response.
Captured traffic is compared against your OpenAPI file. Missing fields, undocumented status codes, nullable mismatches — all identified automatically.
Sentinel generates JSON Patch operations and writes them directly to your YAML or JSON spec file — preserving comments, formatting, and $ref structure.
The core loop
From a solo developer patching specs locally to an enterprise team with governance, rulesets and consumer notifications.
A lightweight local HTTP/HTTPS proxy intercepts test traffic. No code changes needed — just set an env var and run your tests.
Three-phase engine handles additional properties, nullable values, type widening, enum extensions and $ref deduplication — keeping your spec DRY.
See exactly which endpoints and status codes your tests exercise. Spot gaps before they become production incidents.
Side-by-side colour-coded diffs between any two spec snapshots. Breaking changes highlighted in red with a badge.
Every PR automatically gets a structured summary — breaking changes, new endpoints, coverage, and a link to the full diff. Works with GitHub and GitLab.
When a breaking change lands, the consumers who depend on that endpoint are notified automatically — email, Slack, or custom webhook.
Define naming conventions, require examples, enforce breaking change policies. Built-in rulesets and custom JS bundles.
Every run produces a timestamped changelog entry — author, PR link, and a human-readable list of every API change. Shareable via public URL.
Don't want to run tests through a proxy? Feed in a HAR file or Postman collection instead — the same diff and patch engine runs on the recorded traffic.
The CLI is free, open source, and works completely offline.
Install
$ npm install -g @apinotes/sentinel1. Initialise — create a config file
$ sentinel init openapi.yaml
✔ Created sentinel.yml
Edit it to tell Sentinel how to start your server and run your tests.sentinel.yml
capture:
openapi.yaml:
server:
url: http://localhost:3000
command: node server.js
ready_endpoint: /health
requests:
run:
command: npm test
proxy_variable: SENTINEL_PROXY
ruleset:
- breaking-changes
- naming:
properties: camelCase
pathComponents: param-case2. Capture traffic and patch your spec
$ sentinel capture openapi.yaml --update documented
⠿ Starting server... ready
⠿ Running tests via proxy (npm test)
⠿ 45 requests captured
Routing interactions
✓ 43 matched documented paths
⚠ 2 unmatched (undocumented endpoints)
Generating patches
✓ POST /users Added 'role' to 201 response body
✓ GET /users/{id} Marked 'nickname' as nullable
✓ POST /orders Added 422 response schema
⚠ POST /auth/login Required field 'device_id' never observed
Coverage
✓ GET /users Request Body, 200 response
✓ POST /users 201 response
× GET /users/{id} (no traffic)
78% coverage of documented operations
✔ openapi.yaml patched — 3 changes written
✖ 1 unpatchable diff — see above
Exit code 13. Run in CI — diff + lint all specs
$ sentinel run
Scanning for OpenAPI specs...
Found: openapi.yaml, admin.yaml
Diffing against base branch
openapi.yaml ❌ 1 breaking change ✅ 2 new endpoints
admin.yaml ✅ No breaking changes
Linting rulesets
openapi.yaml ⚠ 2 naming violations
admin.yaml ✅ All rules passed
→ PR comment posted to GitHub PR #142name: ApiNotes Sentinel Check
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Sentinel Check
run: npx @apinotes/sentinel run
env:
SENTINEL_TOKEN: ${{ secrets.SENTINEL_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Every pull request gets a structured summary — breaking changes flagged in red, no noise.
| API | Breaking | New endpoints | Updated schemas | Coverage |
|---|---|---|---|---|
| openapi.yaml | ❌ 1 breaking | ✅ 2 added | ✅ 3 updated | 84% |
| admin.yaml | ✅ None | ✅ None | ✅ 1 updated | 91% |
View full diff on ApiNotes Sentinel →
From solo devs to enterprise engineering orgs.
Run the CLI locally. Get spec patches written directly to your file. No account, no internet connection required.
Push results to the cloud from CI. See visual diffs on pull requests and share spec links with teammates.
Manage governance rulesets for the org. Review API changelogs. Set breaking change policies. Get notified when consumers are affected.
View API health scorecards and coverage dashboards. Track breaking change frequency and documentation completeness over time.
The CLI is free forever. Pay only for the cloud platform.
CLI · Local use · Forever free
For teams shipping APIs together
For large orgs with compliance needs
SENTINEL_TOKEN, the CLI works entirely offline — no requests are made to any external server. Your spec files, source code, and traffic are never transmitted./users/{userId} style patterns. In interactive mode it asks you to confirm; in automatic mode it accepts the best proposal.SENTINEL_TOKEN and GITHUB_TOKEN in your CI environment and run sentinel run. Sentinel scans for OpenAPI specs, diffs against the base branch, runs rulesets, and posts (or updates) a single PR comment with the results. It never spams multiple comments.ApiNotes Sentinel is coming soon. Leave your email and be the first to know — plus an early-adopter discount.
No spam. Unsubscribe any time.