Sunsetting /v0: A Migration Guide and Timeline

On June 12, 2024, we shipped Forge v1. It's been almost a year. v0 has served us well—it proved the market wanted better weather and geocoding APIs. But it's time to move forward. The v0 API will be fully sunset on December 31, 2026. This gives you 19 months from today to migrate. We know some of you are running v0 in production, and we want to make this transition as smooth as possible.

Timeline

Now (May 2025): v0 still works 100%. No changes to v0 endpoints or behavior.
June 2025: v0 responses will include a deprecation warning header.
July 2026: v0 rate limits drop from 300 req/min to 100 req/min.
December 31, 2026: v0 endpoints return 410 Gone.

We understand that migrating production APIs takes time. We're giving you nearly two years to complete this work. If you need an extension, reach out to our support team—we can discuss extended timelines for enterprise customers.

Why v1 Exists: The Key Differences

v0 used query parameter authentication and returned flat JSON responses. v1 introduced two major improvements that fundamentally change how you interact with our API.

First, response envelopes: Every v1 response wraps your data, metadata, and status in a consistent structure. This makes client code cleaner and error handling standardized. Instead of checking HTTP status codes and parsing error responses differently, you always get the same envelope shape.

Second, bearer token authentication: v0 used ?key=... in the query string. v1 uses Authorization headers, which is more secure and follows HTTP standards. Query string keys leak into logs, browser history, and cache headers. Bearer tokens stay private.

v0 also lacked rate limit visibility. v1 responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so your client can make intelligent retry decisions before hitting a limit.

Migration: By Example

Here's a v0 call:

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

Response (flat JSON):

{
  "city": "London",
  "temperature": 15.2,
  "humidity": 72,
  "condition": "Cloudy"
}

In v1, you'd query by coordinates instead of city name. Use the geocoding endpoint first:

curl -H "Authorization: Bearer fg_live_abc123" \
  "https://forge-api.dev/v1/weather?lat=51.51&lon=-0.13&units=metric"

Response (envelope-wrapped):

{
  "status": "ok",
  "data": {
    "temperature": 15.2,
    "humidity": 72,
    "condition": "Cloudy"
  },
  "meta": {
    "request_id": "req_abc789",
    "credits_used": 1,
    "generated_at": "2025-05-20T10:30:15Z"
  }
}

Step-by-Step Migration

Step 1: Generate a v1 API key. Log in to your dashboard and create a new token under Settings. It'll start with fg_live_. Keep your v0 keys around for now—they still work.

Step 2: Update your authentication. Replace ?key=... with an Authorization header in your code.

Step 3: Update your response parsing. You now need to unwrap the envelope. Instead of accessing response.temperature, access response.data.temperature.

Step 4: Use coordinates instead of city names. For weather queries, use lat/lon. If you have addresses or cities, use our geocoding endpoint first to resolve them to coordinates.

Using an Official SDK

If you prefer not to hand-roll the migration, our official JavaScript, Python, and Go SDKs handle all this for you. They use v1 under the hood and provide a clean, documented API. All three are open source and free to use.

Extended Support

If you're a long-term customer facing hardship with the migration deadline, we're open to discussing extended support. Reach out to our support team at support@forge-api.dev with your use case. We make these decisions on a case-by-case basis.

We've published a detailed v0-to-v1 migration guide with code examples for Node.js, Python, Go, and cURL at forge-api.dev/docs/migration.