Docs·Concepts·Versioning

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

It is Goable's policy not to make breaking changes to /v1 endpoints in place. If a new shape is needed, the old endpoint is kept in parallel for at least 12 months after the new one launches. Sunset dates appear in the Deprecation and Sunset response headers per RFC 8594.

Engine version

Distinct from the API version is the scoring engine version, set via the deployment's ENGINE_VERSION env var and exposed on GET /v1/health (top-level version field). 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). For audit reproducibility, every score response carries a session_id; the audit log row it maps to (when your tenant has one) persists the engine version, the full raw weather sample set, and the provider chain that produced that specific score.

Deprecation timelines

Announcement: sunsetting endpoints land in the changelog plus an 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.