Concepts
Baselines, diffs, severity levels, ignore rules, and schedules.
Baseline
A baseline is a versioned snapshot of a healthy response:
- HTTP status code
- Response headers you care about
- JSON (or text) body
Only one baseline is active per endpoint. New captures bump the version and deactivate the previous active baseline.
Check
A check fetches the endpoint again and stores the live response. Checks can be triggered from the console, a schedule, or the CLI (apidiff check against files or a URL). A public REST API is on the roadmap.
Diff
A diff compares the active baseline body (and status) to a check result. Hosted checks default to schema mode: leaf value churn is ignored so alerts stay on contract changes. Switch an endpoint to full mode to include value changes.
Changes are classified by severity:
| Severity | Examples |
|---|---|
| Breaking | Field removed, type changed, nullability changed, status class change (2xx→4xx), OpenAPI contract violation |
| Warning | Value changed (full mode), response header changed, status change within the same class (200→201) |
| Info | Field added, other non-breaking churn |
Array items with stable identity keys (id, _id, uuid, key, slug, name) are matched by identity so reordering does not look like mass field churn.
When an endpoint was imported from OpenAPI with a response schema, live bodies are also validated against that contract.
Ignore rules
Volatile leaf names such as request_id, timestamp, created_at, updated_at, etag, nonce, and uuid are ignored by default so alerts stay on contract changes.
Workspace-specific ignore rules are managed on each endpoint detail page and applied by the engine when present.
Schedules
Schedules run checks on an interval (for example hourly). Use them for third-party APIs that change when you are not deploying.