API v3 Migration Plan

This document covers the phased approach to migrating from v2 to v3 of the Ledger API. The migration will be non-breaking for existing clients during a 6-month deprecation window.

Phase 1: Schema Updates

All response envelopes will be standardized to include metadata fields: requestId, timestamp, and pagination cursors.

{
  "data": [...],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-03-03T09:15:00Z",
    "cursor": "eyJpZCI6MTB9"
  }
}

Phase 2: Auth Flow

OAuth 2.1 with PKCE replaces the current API key model. Existing keys will continue to work during the deprecation period with rate-limiting notices.

Phase 3: Rate Limiting

• Free tier: 100 req/min
• Pro tier: 1,000 req/min
• Enterprise: 10,000 req/min
• Burst allowance: 2x for 30 seconds