1. [    Home ](/)
2. [Guides](/guides)
3. [Best Practices](/guides?category=29)
4. API Versioning and Migration Guide
 
 intermediate Best Practices      20 min       4 steps      9 min read  

# API Versioning and Migration Guide

  A  admin  April 15, 2026  

 

 

       

 

 

 

 

 ##     Prerequisites 

 

 

 

 

 ## On this page

  
  4 steps total 

 [    Back to top ](#main-content) 

 ## Versioning Strategy

Aelix uses **URL path versioning**. The major version is embedded in the base path:

<https://api.aelix.digitalapi.ai/v1/accounts> ← Current stable  
<https://api.aelix.digitalapi.ai/v2/accounts> ← Next major version (beta)

Minor changes (new optional fields, new endpoints) are non-breaking and released into the same major version without notice. Breaking changes always increment the major version.

## Deprecation Timeline

PhaseDurationWhat HappensStable—Full support and SLADeprecated12 monthsWarning headers added; new features go to v+1 onlySunset3 monthsReturns 410 Gone for all requestsDeprecation is announced via email, the [changelog](/changelog), and the Sunset HTTP response header.

## Detecting Deprecation Warnings

Check for the Deprecation and Sunset headers in API responses:

Deprecation: true  
Sunset: Sat, 01 Jan 2027 00:00:00 GMT  
Link: &lt;[https://aelix.digitalapi.ai/migration/v1-to-v2&amp;gt](https://aelix.digitalapi.ai/migration/v1-to-v2&gt);; rel="deprecation"

## Migration Checklist: v1 → v2

1. Read the v2 [migration guide](/docs/migration-v1-v2) and identify breaking changes
2. Create a v2 test environment and run your integration tests against it
3. Update base URL from /v1/ to /v2/ in your configuration
4. Update request/response models to match new field names
5. Deploy to production with a feature flag to switch traffic gradually
6. Monitor error rates for 48 hours before fully retiring v1 calls



 

 

 

 ### Tags

Tags

[Versioning](/taxonomy/term/42)