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

# API Versioning

> Understanding Gately API versions

## Current Version

The Gately API is currently at version **v1**. The standard base URL is:

```bash theme={null}
https://api.usegately.com/api/v1
```

## Health Check

Check API status and version info:

```bash theme={null}
curl https://api.usegately.com/api/v1/health
```

Response:

```json theme={null}
{
  "status": "healthy",
  "service": "gately-api",
  "version": "1.0.0",
  "api_version": "v1",
  "supported_versions": ["v1"],
  "base_url": "https://api.usegately.com/api/v1",
  "timestamp": "2024-12-29T10:00:00.000Z",
  "endpoints": {
    "auth": "/api/v1/auth/*",
    "members": "/api/v1/members/*",
    "campaigns": "/api/v1/campaigns/*",
    "plans": "/api/v1/plans/*",
    "contacts": "/api/v1/contacts/*",
    "discussions": "/api/v1/discussions/*",
    "webhooks": "/api/v1/webhooks/*"
  }
}
```

## Legacy Path (Deprecated)

The legacy `/sdk` path is still supported for backward compatibility:

```bash theme={null}
# Legacy (deprecated)
https://api.usegately.com/sdk/members

# New standard (recommended)
https://api.usegately.com/api/v1/members
```

<Warning>
  The `/sdk/*` path is deprecated and will be removed in a future version.
  Please migrate to `/api/v1/*` for all new integrations.
</Warning>

## Version Strategy

Gately uses URL-based versioning for major API changes. The current version is implicit (v1), but future versions will be explicitly versioned:

| Version | Base URL  | Status                |
| ------- | --------- | --------------------- |
| v1      | `/api/v1` | Current (recommended) |
| legacy  | `/sdk`    | Deprecated            |
| v2      | `/api/v2` | Future                |

## Backward Compatibility

We maintain backward compatibility within major versions:

* **Minor updates**: New endpoints, optional parameters, additional response fields
* **Major updates**: Breaking changes require a new version

## Deprecation Policy

When we release a new major version:

1. The previous version remains available for **12 months**
2. Deprecation notices are sent via email and dashboard
3. Migration guides are provided in documentation

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Latest Version" icon="rocket">
    New integrations should use the latest stable version
  </Card>

  <Card title="Monitor Deprecations" icon="bell">
    Subscribe to API changelog for updates
  </Card>
</CardGroup>

## Rate Limiting by Version

Rate limits are consistent across versions:

* **Standard endpoints**: 100 requests/minute
* **Authentication**: 20 requests/minute
* **Bulk operations**: 10 requests/minute

## Headers

Include version information in your requests for debugging:

```bash theme={null}
curl -X GET "https://api.usegately.com/api/v1/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 1"
```

<Note>
  The `X-API-Version` header is optional and used for debugging purposes.
  The URL path determines the actual API version used.
</Note>