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

# API Versioning

> Understand how Xerobi handles API versioning and backward compatibility

## API Versioning Strategy

Xerobi uses a date-based versioning system to ensure predictable API behavior and smooth transitions between versions.

## Version Format

Versions follow the format `YYYY-MM-DD` and are specified in the `Xerobi-Version` header:

```bash theme={null}
curl -X GET "https://api.hixbe.com/payment/payment_intents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Xerobi-Version: 2026-01-01"
```

## Current Version

> [!NOTE]
>
> **Latest Version**: `2026-01-01`
>
> This is the recommended version for all new integrations. It includes the latest features, improvements, and security enhancements.

## Version Lifecycle

### Version States

| State | Description | Support Level |
| - | - | - |
| **Active** | Fully supported with new features | Full support |
| **Deprecated** | Still functional but not recommended | Limited support |
| **Sunset** | No longer supported | No support |

### Deprecation Timeline

When a new version is released:

1. **Active Period**: 12 months of full support
2. **Deprecation Notice**: 3 months advance warning
3. **Deprecated Period**: 6 months of limited support
4. **Sunset**: Version retired

## Backward Compatibility

### What We Guarantee

* Existing API endpoints remain functional
* Request/response formats are stable
* Breaking changes are introduced in new versions only
* Deprecation notices provided 3+ months in advance
* Migration guides provided for major changes

### What May Change

* New optional fields added to responses
* New endpoints added
* New optional parameters added to requests
* Performance improvements
* Bug fixes that don't change behavior

## Version Headers

### Required Headers

```bash theme={null}
# Always include the version header
-H "Xerobi-Version: 2026-01-01"
```

### Version Detection

If no version header is provided, the API will:

1. Return a `400 Bad Request` error
2. Include a message specifying the required header

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_VERSION_HEADER",
    "message": "The Xerobi-Version header is required",
    "details": {
      "required_header": "Xerobi-Version",
      "current_version": "2026-01-01"
    }
  }
}
```

## Version-Specific Features

### Version 2026-01-01 Features

> [accordion] Payment Gateway Enhancements
>
> * Enhanced webhook security with signature verification
> * Improved error messages with detailed field validation
> * New idempotency key support for all endpoints
> * Expanded payment method support

> [accordion] SMS Gateway Improvements
>
> * Bulk SMS with individual delivery tracking
> * Enhanced sender ID validation
> * Template management system
> * Improved balance reporting

> [accordion] Certification & Badge Updates
>
> * Enhanced credential verification
> * New audit logging capabilities
> * Improved badge management
> * Program-based credential organization

## Migration Guide

### Upgrading to 2026-01-01

**1. Review changelog**

Check the [changelog](https://docs.xerobi.com/changelog.md) for all changes in the new version.

**2. Test in sandbox**

Update your integration to use the new version in sandbox first:

```bash theme={null}
# Test with new version
curl -X GET "https://sandbox.api.hixbe.com/payment/payment_intents" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Xerobi-Version: 2026-01-01"
```

**3. Update production**

Once testing is complete, update your production code:

```javascript theme={null}
// Update your API client
const client = new HixbeClient({
  apiKey: process.env.HIXBE_API_KEY,
  version: '2026-01-01'  // Update this line
});
```

**4. Monitor for issues**

Watch your application logs and dashboard for any issues after deployment.

## Version History

| Version | Release Date | Status | Notes |
| - | - | - | - |
| `2026-01-01` | Dec 2025 | Active | Latest features and improvements |
| `2025-06-01` | Jun 2025 | Deprecated | Use 2026-01-01 |
| `2025-01-01` | Jan 2025 | Sunset | No longer supported |

## Best Practices

### Version Management

* Always specify the version header explicitly
* Use the latest version for new integrations
* Test version upgrades in sandbox first
* Monitor deprecation notices in your dashboard
* Keep your integration documentation updated

### Code Organization

```javascript JavaScript (Recommended) theme={null}
// Centralized version management
const HIXBE_CONFIG = {
  version: '2026-01-01',
  baseUrl: process.env.NODE_ENV === 'production'
    ? 'https://api.hixbe.com'
    : 'https://sandbox.api.hixbe.com'
};

class HixbeClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.version = HIXBE_CONFIG.version;
    this.baseUrl = HIXBE_CONFIG.baseUrl;
  }

  async request(endpoint, options = {}) {
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Xerobi-Version': this.version,
      'Content-Type': 'application/json',
      ...options.headers
    };

    return fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers
    });
  }
}
```

```python Python (Recommended) theme={null}
# Configuration management
HIXBE_CONFIG = {
    'version': '2026-01-01',
    'base_url': os.getenv('HIXBE_BASE_URL', 'https://api.hixbe.com')
}

class HixbeClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.version = HIXBE_CONFIG['version']
        self.base_url = HIXBE_CONFIG['base_url']

    def _get_headers(self):
        return {
            'Authorization': f'Bearer {self.api_key}',
            'Xerobi-Version': self.version,
            'Content-Type': 'application/json'
        }
```

## Support and Migration Help

> [card] [Authentication](https://docs.xerobi.com/faq-guides/authentication.md)
>
> Learn about API keys and headers

> [card] [Best Practices](https://docs.xerobi.com/faq-guides/best-practices.md)
>
> Version management best practices

> [card] [Changelog](https://docs.xerobi.com/changelog.md)
>
> See all version changes and updates

> [card] [Support](mailto:support@xerobi.com)
>
> Get help with version upgrades


## Related topics

- [Authentication](https://docs.xerobi.com/faq-guides/authentication.md)
- [Xerobi Payment API Introduction](https://docs.xerobi.com/payment-api/introduction.md)
- [Xerobi Certification & Badge API Introduction](https://docs.xerobi.com/certify/introduction.md)
- [Xerobi SMS Gateway API Introduction](https://docs.xerobi.com/sms-api/introduction.md)
- [Quickstart Guide](https://docs.xerobi.com/faq-guides/quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.