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

# API Versioning

> Understanding API versions and migration guide

The G-Tateth API uses versioning to ensure backward compatibility while allowing us to introduce new features and improvements.

## Current Versions

* **v1** (Current) - Stable, production-ready API
* **v2** (Coming Soon) - Next generation API with enhanced features

## Versioning Strategy

### URL-Based Versioning

API versions are specified in the URL path:

```
https://api.g-tateth.com/api/v1/conversations
https://api.g-tateth.com/api/v2/conversations  # Future
```

### Version Headers

You can also specify the version using headers:

```http theme={null}
GET /api/conversations HTTP/1.1
Host: api.g-tateth.com
X-API-Version: v1
```

<Note>
  If no version is specified, the latest stable version (v1) is used by default.
</Note>

## Version Lifecycle

### Stable Versions

* **Long-term support** - Maintained for at least 12 months
* **Backward compatible** - No breaking changes
* **Security updates** - Regular security patches
* **Bug fixes** - Critical bug fixes

### Deprecated Versions

* **6-month notice** - We provide 6 months notice before deprecation
* **Migration guide** - Detailed migration documentation
* **Support** - Limited support during deprecation period

### Sunset Versions

* **No longer supported** - No updates or fixes
* **May be removed** - Endpoints may stop working
* **Migration required** - Must upgrade to supported version

## Migration Guide

### From v0 to v1

If you're using the legacy API (no version prefix), migrate to v1:

**Before:**

```http theme={null}
GET /api/conversations
```

**After:**

```http theme={null}
GET /api/v1/conversations
```

### Breaking Changes

We document all breaking changes in our [changelog](/changelog). Common changes include:

* **Endpoint paths** - URL structure changes
* **Request/response formats** - Schema changes
* **Authentication** - Auth method changes
* **Error codes** - Error code updates

## Best Practices

### 1. Always Specify Version

```javascript theme={null}
// ✅ Good - Explicit version
const response = await fetch('https://api.g-tateth.com/api/v1/conversations');

// ❌ Bad - Relies on default
const response = await fetch('https://api.g-tateth.com/api/conversations');
```

### 2. Pin Your Version

Don't automatically upgrade to new versions. Test thoroughly first:

```javascript theme={null}
const API_VERSION = 'v1'; // Pin to specific version
const baseUrl = `https://api.g-tateth.com/api/${API_VERSION}`;
```

### 3. Monitor Deprecation Warnings

The API includes deprecation warnings in responses:

```http theme={null}
HTTP/1.1 200 OK
X-API-Version: v1
X-API-Deprecated: true
X-API-Sunset: 2025-01-01
Warning: 299 - "API version v1 will be sunset on 2025-01-01. Please migrate to v2."
```

### 4. Test Before Upgrading

Always test in a staging environment before upgrading:

```javascript theme={null}
// Staging environment
const stagingUrl = 'https://staging-api.g-tateth.com/api/v2';

// Production environment
const productionUrl = 'https://api.g-tateth.com/api/v1';
```

## Version-Specific Features

### v1 Features

* RESTful API design
* JSON request/response format
* Bearer token authentication
* Webhook support
* Rate limiting
* Pagination

### v2 (Planned)

* GraphQL support
* WebSocket subscriptions
* Enhanced filtering
* Batch operations
* Advanced analytics

## Changelog

See our [changelog](/changelog) for detailed version history and changes.

## Support

Questions about versioning? Contact us:

* **Email**: [support@g-tateth.com](mailto:support@g-tateth.com)
* **Documentation**: [https://docs.g-tateth.com](https://docs.g-tateth.com)