voyageai-cli

# API Versioning The platform uses URL-based versioning to manage API changes while maintaining backward compatibility. Major versions are breaking changes; minor versions are backward-compatible. ## Version Format API versions follow semantic versioning in the URL: `/v{major}/` Current version: `/v2/` Previous version: `/v1/` (legacy, deprecated) The version is part of the base URL: `https://api.example.com/v2/` ## Major Versions Major versions represent breaking changes (e.g., removed endpoints, changed response format, different authentication). Old major versions are supported for 2 years before sunset. **v1 Timeline**: - Released: 2023-01-01 - Sunset date: 2026-01-01 - Status: Deprecated (security updates only) **v2 Timeline**: - Released: 2024-01-01 - Sunset date: 2028-01-01 (estimated) - Status: Current, fully supported Plan migrations well in advance. Sunset notifications are sent 6 months before end-of-life. ## Migrating Between Versions Migrate by updating your base URL and reviewing breaking changes documentation. Breaking changes in v2 vs. v1 include: - `/v1/resources` → `/v2/resources` (same structure, but v2 has additional fields) - Removed pagination cursors; now uses offset-based only (v1 supported both) - Response format includes additional metadata in v2 Review the [Migration Guide](../database/migration-guide.md) for detailed changes. ## Minor Versions Minor versions add new functionality without breaking existing behavior. The API minor version is not in the URL; instead, it's indicated by the `API-Version` header: ``` API-Version: 2.3 ``` This header is informational; you don't need to specify it in requests. New fields in responses are backward-compatible. Ignore unknown fields; they don't affect your code. ## Feature Flags (Betas) Beta features are opt-in and available in the current version: ``` Authorization: Bearer <token> X-Feature-Flag: beta.new_analytics_api ``` Request beta features via the dashboard. Beta features may change before general availability (GA). ## Deprecation Notices When endpoints are deprecated, responses include a deprecation warning header: ``` Deprecation: true Sunset: Sat, 01 Jan 2027 00:00:00 GMT Link: <https://docs.example.com/migration>; rel="deprecation" ``` Applications should log these warnings and plan migrations. ## Version Support Matrix | Version | Released | Sunsets | Security | Features | Status | |---------|----------|---------|----------|----------|--------| | v1 | 2023-01 | 2026-01 | Updates | Frozen | Deprecated | | v2 | 2024-01 | 2028-01 | Yes | Yes | Current | ## Backwards Compatibility v2 maintains backwards compatibility by: - Never removing fields from responses - Adding new fields at the end - Never removing query parameters - Supporting both old and new behaviors where possible This allows gradual adoption of new features. ## Environment-Specific Versions Sandbox (`https://sandbox-api.example.com/v2/`) may have beta features not yet in production. Test new features in sandbox before using in production. Production (`https://api.example.com/v2/`) is stable and suitable for production workloads. ## API Changelog The changelog documents all changes per version: - New endpoints - Deprecated endpoints - Breaking changes - New fields and parameters - Bug fixes Subscribe to the changelog via the dashboard to receive notifications. ## Version Negotiation For advanced use cases, request a specific version: ``` Accept-Version: 2.3 ``` If the requested version isn't available, the API returns the closest compatible version and includes the actual version in the response header: ``` API-Version: 2.2 ``` If you request a sunset version, the API returns 410 Gone.