Compatibility policy
What changes within v2 and what requires a new major version.
The version in the path (/api/v2/) lets two major versions run side by side. Within v2, we follow an additive-only policy so you can integrate once and upgrade safely.
We may change without a version bump
- Add new fields to any object
- Add new enum or union members (
warnings[].code,issues[].id,error.code,unit,status) - Add new issue ids and retune thresholds/severities
- Upgrade a
Measurefrom estimated to measured (dropestimated: true) - Add new endpoints and optional request parameters
We will not change within a major version
- Remove or rename a field
- Change a field's type or unit
- Change the meaning of an existing enum member
- Change
methodology.basis(the emissions basis) - Start omitting a field that was always present
Deprecation
When a field must be retired, we announce it via:
- A
warnings[]entry with codeDEPRECATED_FIELD - A
DeprecationHTTP header
The field keeps working for at least one further major version.
Emissions basis
methodology.basis is currently fullPage. Headline emissions (co2.perVisit, grade, issue detection) derive from full-page weight. Changing the basis is a breaking change.
The above-the-fold figure is still reported as co2.range.min and measurement.aboveTheFold.
OpenAPI as source of shape
Field names, types, and required-ness live in the generated OpenAPI document:
GET /api/v2/openapi.jsonIt is generated from TypeScript response types and guarded by drift tests — the spec cannot disagree with the code.
Semantic meaning and policy live in this documentation.
Historical boundary
Scans before 2026-08-22 are not comparable with later scans due to grid-intensity fixes, geolocation corrections, and rounding changes.