Current versions
Version in URLs
The version number appears in the endpoint path:Breaking vs. non-breaking changes
Breaking changes (require code updates)
These changes only occur in major version bumps:- Removing an endpoint
- Removing a response field
- Removing a query parameter
- Adding a new required parameter
- Changing a field’s data type
- Renaming a field or resource
- Changing response codes or error types
- Modifying authorization scopes
Non-breaking changes (additive)
These can happen at any time without version changes:- Adding a new endpoint
- Adding a new optional parameter
- Adding a new response field
- Adding new OAuth scopes
- Changing error message text
- Nulling fields for privacy/security reasons
Release schedule
Deprecation policy
When we release a new major version:- Deprecation: Previous version is marked deprecated
- Support period: Deprecated version continues to work for a defined period
- Retirement: Deprecated version is removed
Definitions
Staying informed
Get notified about changes:Changelog
All platform changes and updates.
Forum Announcements
Breaking change notices.
@XDevelopers
Platform news and updates.
Newsletter
Monthly digest.
Migration resources
When a new version is released, we provide:- Migration guides: Step-by-step upgrade instructions
- Endpoint mapping: v1 to v2 equivalents
- Data format changes: Object model differences
Migration overview
Current migration guidance.
Endpoint map
v1 to v2 endpoint mapping.
Best practices
Use v2
Start new projects on the latest version.
Monitor announcements
Subscribe to changelog and forum updates.
Test changes
Test in development before production updates.
Plan migrations
Don’t wait until deprecation to upgrade.