Skip to Content
CarbonFooterv2.0

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 Measure from estimated to measured (drop estimated: 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:

  1. A warnings[] entry with code DEPRECATED_FIELD
  2. A Deprecation HTTP 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.json

It 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.

On this page