> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arqitech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning & Deprecation

> Learn about our API versioning strategy and deprecation policy to ensure smooth migrations.

## API Versioning

Our API uses versioning to ensure backward compatibility while introducing new features and improvements. Understanding our versioning approach helps you build resilient integrations.

### Current Version

The Arqitech Router API is currently at version **v1**. All endpoints use the version prefix in the URL path:

* `https://api.dkit.xyz/v1/quote`
* `https://api.dkit.xyz/v1/track`
* `https://api.dkit.xyz/v1/tokens`
* `https://api.dkit.xyz/v1/providers`

### Version Headers

API responses include version information in custom headers:

| Header           | Description            | Example |
| ---------------- | ---------------------- | ------- |
| `x-api-version`  | Current API version    | `v1`    |
| `x-api-versions` | Available API versions | `v1`    |

***

## Deprecation Policy

We follow a structured deprecation process to give developers ample time to migrate to newer API versions when they become available.

### Deprecation Notifications

When an API version is scheduled for deprecation, we will:

1. **Announce** the deprecation at least 6 months in advance
2. **Include deprecation headers** in API responses
3. **Provide migration guides** and documentation
4. **Send notifications** to registered developers

### Planned Deprecation Headers

When deprecation is active, API responses will include:

```http theme={null}
HTTP/1.1 200 OK
Warning: 299 - "This API version is deprecated and will be removed soon"
x-api-deprecated: true
x-api-sunset-date: 2026-06-01T00:00:00Z
```

| Header              | Description                                 |
| ------------------- | ------------------------------------------- |
| `Warning`           | HTTP standard deprecation notice (code 299) |
| `x-api-deprecated`  | Boolean indicating deprecation status       |
| `x-api-sunset-date` | ISO 8601 date when version will be removed  |

***

## Sunset Timeline

Our standard deprecation timeline ensures you have sufficient time to migrate:

<Steps>
  <Step title="Announcement Phase">
    <p>
      <strong>Duration:</strong> 6 months before deprecation
    </p>

    <p>
      New version released, documentation updated, migration guides published
    </p>
  </Step>

  <Step title="Deprecation Phase">
    <p>
      <strong>Duration:</strong> 6-12 months
    </p>

    <p>API marked as deprecated, warning headers included in responses</p>
  </Step>

  <Step title="Sunset Phase">
    <p>
      <strong>Duration:</strong> 30 days before removal
    </p>

    <p>Final notices sent, increased warning visibility</p>
  </Step>

  <Step title="Removal">
    <p>API version removed, requests return 410 Gone status</p>
  </Step>
</Steps>

***

## Handling Deprecation

### Best Practices

<Tabs>
  <Tab title="Monitor Headers">
    ```javascript theme={null}
    // Check for deprecation warnings
    fetch('https://api.dkit.xyz/v1/quote', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(quoteRequest)
    })
    .then(response => {
      // Check deprecation status when available
      if (response.headers.get('x-api-deprecated') === 'true') {
        const sunsetDate = response.headers.get('x-api-sunset-date');
        console.warn(`API v1 is deprecated. Sunset date: ${sunsetDate}`);
        // Trigger migration workflow
      }
      
      // Check for warning header
      const warning = response.headers.get('Warning');
      if (warning && warning.includes('299')) {
        console.warn(`API Warning: ${warning}`);
      }
      
      return response.json();
    });
    ```
  </Tab>

  <Tab title="Error Handling">
    ```javascript theme={null}
    // Handle version-specific errors
    async function makeApiRequest(endpoint, params) {
      try {
        const response = await fetch(
          `https://api.dkit.xyz/v1/${endpoint}`,
          params
        );
        
        if (!response.ok) {
          // Handle 410 Gone for sunset versions
          if (response.status === 410) {
            throw new Error('API version has been sunset');
          }
          throw new Error(`API error: ${response.status}`);
        }
        
        // Log any deprecation warnings
        const deprecated = response.headers.get('x-api-deprecated');
        if (deprecated === 'true') {
          console.warn('Using deprecated API version');
        }
        
        return response.json();
      } catch (error) {
        console.error('API request failed:', error);
        throw error;
      }
    }
    ```
  </Tab>

  <Tab title="Version Tracking">
    ```javascript theme={null}
    // Track API version information
    class ApiVersionManager {
      constructor() {
        this.currentVersion = 'v1';
        this.deprecationStatus = null;
      }
      
      async checkVersion() {
        const response = await fetch('https://api.dkit.xyz/v1/providers');
        
        // Store version info from headers
        this.currentVersion = response.headers.get('x-api-version') || 'v1';
        this.deprecationStatus = {
          isDeprecated: response.headers.get('x-api-deprecated') === 'true',
          sunsetDate: response.headers.get('x-api-sunset-date'),
          warning: response.headers.get('Warning')
        };
        
        return this.deprecationStatus;
      }
      
      getVersionedUrl(endpoint) {
        return `https://api.dkit.xyz/${this.currentVersion}/${endpoint}`;
      }
    }
    ```
  </Tab>
</Tabs>

### Migration Strategy

1. **Early Detection**: Monitor deprecation headers in your production environment
2. **Gradual Migration**: Test new versions in staging before production deployment
3. **Feature Flags**: Use feature flags to switch between API versions
4. **Monitoring**: Track API version usage and deprecation warnings in your logs

***

## Version Compatibility

### Breaking Changes

Breaking changes are only introduced in major version updates (e.g., v1 → v2):

* Removed endpoints
* Changed required parameters
* Modified response structures
* Authentication changes

### Non-Breaking Changes

These changes can occur within the same version:

* New optional parameters
* Additional response fields
* New endpoints
* Performance improvements
* Bug fixes

***

## Example Response

A deprecated API response will look like:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Warning: 299 - "This API version is deprecated and will be removed soon"
x-api-version: v1
x-api-versions: v1, v2
x-api-deprecated: true
x-api-sunset-date: 2026-06-01T00:00:00Z
Date: Mon, 01 Dec 2025 12:00:00 GMT

...
```

***

## Notifications

Stay informed about API changes:

* **GitHub**: Follow our [GitHub repository](https://github.com/el-Dorado-Market) for updates
* **Support**: Contact [brandon@arqitech.com](mailto:brandon@arqitech.com) for migration assistance
* **Status Page**: Check [dkit.instatus.com](https://dkit.instatus.com) for announcements

<Note>
  **Important**: Always implement proper error handling to ensure your
  integration remains robust.
</Note>