Your unit tests pass, you rename a response field, and the frontend breaks in production. ContractWatch snapshots your app's OpenAPI contract, then fails your commit or CI run if a change would break existing clients.

What it catches

• Breaking changes: removed endpoints, removed or retyped response fields, newly required request fields, removed status codes, narrowed enums.
• Schema-name collisions: two Pydantic models with the same name in different modules, which makes OpenAPI component names ambiguous.
• Reliability pitfalls: blocking calls inside async endpoints, HTTP calls without a timeout, duplicate routes, conflicting operation IDs.
• Fixes, not just errors: every finding says what broke, who it hurts, and how to fix it.

Install

pip install contractwatch    # or: uv add --dev contractwatch

Python 3.11+, FastAPI, Pydantic v2.

Use it

contractwatch init     # save the current contract as the baseline (commit .contractwatch/baseline.json)
contractwatch check    # compare against the baseline

Exit codes: 0 safe, 1 blocking change, 2 analysis error.

Changed the API on purpose? Accept it:

contractwatch baseline update

Collisions that aren't breaking show up as warnings:

Commands

Run contractwatch <command> --help for all options.

Pre-commit and CI

contractwatch init offers to install the hook for you (skip with --no-install-hook). Or add it by hand:

repos:
  - repo: local
    hooks:
      - id: contractwatch
        name: ContractWatch
        entry: contractwatch check
        language: system
        pass_filenames: false

In CI, just run contractwatch check; the exit code does the rest.

Configuration

Optional. Put it in contractwatch.toml or [tool.contractwatch] in pyproject.toml:

[tool.contractwatch]
app = "app.main:app"           # skip auto-detection
severity_threshold = "error"   # error | warning | info
baseline = ".contractwatch/baseline.json"
ignore = ["CW110"]             # silence specific codes

[tool.contractwatch.retention]
keep = 20                      # keep the last 20 reports...
days = 7                       # ...or the last 7 days, whichever is stricter

Env vars: CONTRACTWATCH_HOME (reports/cache location), NO_COLOR.

Diagnostic codes

Contributing

uv sync --group dev
uv run ruff check . && uv run mypy && uv run pytest -q

License

MIT