Versioning + compatibility

The HTTP API is the only public surface that respects semantic versioning. The scoring engine evolves continuously; the API contract evolves on tight timelines with explicit deprecation windows.

Path versioning

Every endpoint lives under /v1. A breaking change to an endpoint's wire shape — removed fields, renamed fields, changed types, narrowed enums — ships as a new path under /v2 without removing /v1. You opt in by changing the path; you never get a silent shape change. Adding new optional request fields or new response fields is not a breaking change and ships in place.

Breaking-change policy

Engine version

Distinct from the API version is the scoring engine version (visible in ENGINE_VERSION + the score response's provenance.engineVersion). The engine bumps when scoring math changes — new physics modules, recalibrated curves, new provider chains. Engine bumps do NOT change the wire contract; same request yields the same response shape (possibly a different numeric score). If you need to pin a specific engine version for audit reproducibility, the cohort hash in every response anchors the inputs deterministically regardless of which engine produced the score.

Deprecation timelines

• Announcement — sunsetting endpoints land in the changelog + email to tenants who hit them in the last 30 days.
• Headers — every response from a deprecated path carries Deprecation: true and Sunset: <date>.
• 12-month minimum — the gap between Deprecation announcement and Sunset is at least 12 months. We aim for 18.
• Sunset — after the date, the path returns 410 Gone with the successor endpoint in the body.

Changelog

The signed-in console shows release notes inline (the floating "What's new" button bottom-right). The public-facing record lives at the project's CHANGELOG.md on GitHub.