API Migration Guide

Moving from REST v1 to v2. This guide covers every breaking change and how to update your code.

Authentication

v1 used API keys in query params. v2 uses Bearer tokens in headers.

# v1 (deprecated)
curl https://api.example.com/data?key=abc123

# v2
curl -H "Authorization: Bearer abc123" https://api.example.com/v2/data

Endpoints Changed

v1 Endpointv2 EndpointNotes
GET /usersGET /v2/usersPaginated by default
POST /users/createPOST /v2/usersRESTful naming
GET /users/:id/postsGET /v2/posts?user_id=:idFlattened
DELETE /users/:id/removeDELETE /v2/users/:idRESTful

Response Format

All v2 responses are wrapped:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142
  }
}

Rate Limits

Tierv1v2
Free100/min60/min
Pro1000/min600/min
EnterpriseUnlimited10000/min

Important: v1 will be sunset on June 30, 2026. All API keys will stop working.

Migration Checklist

  • Update auth headers
  • Change endpoint URLs
  • Handle new response wrapper
  • Update rate limit handling
  • Test in staging
  • Deploy to production