Migrating from v0

Migrating from v0 to v1

/v0 was deprecated in June 2025 and is scheduled to sunset on 2026-12-31. All /v0 responses now carry a Deprecation: true header and a Sunset header naming the shutdown date. New integrations should use /v1 exclusively; existing /v0 integrations must migrate before the sunset date or requests will start failing.

What changed

Authentication: /v0 passed the key as a key query parameter; /v1 requires an Authorization: Bearer header.
Response shape: /v0 returned a flat, un-enveloped JSON object; /v1 wraps data in a {status, data, meta} envelope with structured errors.
Fields: /v1 exposes many more fields (forecast, dew point, UV index, pressure, and more) and supports coordinate lookup, unit conversion, and multi-day forecasts, none of which /v0 supported.

Side by side

v0 request (query-param auth, city only):

curl 'https://forge-api.dev/v0/weather?city=london&key=fg_live_xxxxxxxx'

v0 response (flat JSON):

{
  "name": "London",
  "country": "United Kingdom",
  "lat": 51.51,
  "lon": -0.13,
  "temp": 18.2,
  "humidity": 72,
  "wind": 14.4,
  "desc": "Partly cloudy",
  "code": 1003,
  "dt": 1752487200
}

v1 request (Bearer auth, same city):

curl 'https://forge-api.dev/v1/weather?city=london' \
  -H 'Authorization: Bearer fg_live_xxxxxxxx'

v1 response (enveloped, richer):

{
  "status": "ok",
  "data": {
    "location": { "name": "London", "country": "United Kingdom", "lat": 51.51, "lon": -0.13 },
    "current": {
      "temp": 18.2,
      "humidity": 72,
      "wind_speed": 14.4,
      "condition": { "code": 1003, "text": "Partly cloudy", "icon": "partly-cloudy" },
      "observed_at": "2026-07-14T10:00:00Z"
    }
  },
  "meta": { "request_id": "req_8f2a1c4e9b3d", "credits_used": 1, "units": "metric", "generated_at": "2026-07-14T10:00:03Z" }
}

Field mapping

v0 field	v1 equivalent	Notes
`name`	`data.location.name`	Unchanged meaning.
`country`	`data.location.country`	Unchanged meaning.
`lat` / `lon`	`data.location.lat` / `data.location.lon`	Unchanged meaning.
`temp`	`data.current.temp`	v1 also adds `feels_like` and a Celsius-always `temp_c`.
`humidity`	`data.current.humidity`	Unchanged meaning.
`wind`	`data.current.wind_speed`	Now accompanied by `wind_deg` and `wind_dir`.
`desc`	`data.current.condition.text`	Now part of a structured `condition` object.
`code`	`data.current.condition.code`	Same numeric condition codes.
`dt`	`data.current.observed_at`	Changed from unix seconds to ISO 8601.
(n/a)	`meta.request_id`, `meta.credits_used`	New in v1; useful for support and billing reconciliation.

Migration checklist

Move your key from the key query parameter into an Authorization: Bearer header.
Update response parsing to read from data.current.* instead of the top level, and check status before assuming success.
Convert dt (unix seconds) consumers to parse the ISO 8601 observed_at string instead.
Add error handling for the structured {status:"error", error:{code,...}} shape described in errors.
Switch traffic over gradually and confirm the Deprecation header disappears from your responses once fully migrated.

Timeline

June 2025 — /v0 marked deprecated; Deprecation and Sunset headers added to all v0 responses.
Now — both versions run side by side; new integrations must use /v1.
2026-12-31 — /v0 sunsets permanently. Requests after this date will fail.