API Contract Audit

OpenAPI-driven verification for live API responses and breaking contract changes. Validate status codes, content types, JSON response schemas, and required request parameters before promoting an API deployment.

Release status: Initial public alpha. Mutating requests are disabled by default and should only be enabled against dedicated test data with explicit cleanup behavior.

Features

• OpenAPI 3.x YAML and JSON documents from files or URLs
• Live status, content-type, and JSON-schema response validation
• Local $ref resolution and OpenAPI nullable conversion
• Required query and header parameter checks
• Breaking-change detection for removed paths, operations, and responses
• Detection of newly required operation parameters
• Safe-by-default GET and HEAD execution
• Explicit opt-in for POST, PUT, PATCH, and DELETE
• Environment-variable expansion for request configuration
• JSON and Markdown reports with GitHub job summaries
• Docker image and GitHub Action

Install and run

Requires Node.js 22.19 or newer.

npm install
npm run audit -- --config config.example.yaml

Compare the current specification with a retained contract:

npm run audit -- --config config.example.yaml --baseline-spec openapi.baseline.yaml

Reports are written to reports/api-contract-report.json and reports/api-contract-report.md. Contract failures return exit code 1; configuration and execution errors return exit code 2.

Authenticated requests

Configuration values support environment variables:

headers:
  authorization: "Bearer ${API_AUDIT_TOKEN}"

Never commit tokens or production credentials.

Safety

Mutating methods require allow_mutating_methods: true. Use them only against non-production test fixtures or operations designed to be safely repeatable.

Project boundary

This repository is a generic contract engine. It contains no private schemas, credentials, production API addresses, client payloads, or internal compatibility policy.

License

MIT © 2026 CodeVelo.dev LLC.