---
title: Deprecations
description: Current and upcoming API deprecations in TraceRTM with migration timelines
---

# Deprecations

This page lists all current and upcoming deprecations in the TraceRTM API. Subscribe to deprecation notifications in your dashboard to stay informed of changes.

## Current Deprecations

### None Currently

There are no active deprecations at this time. The v1 API is stable and fully supported.

---

## Upcoming Deprecations

### Scheduled for 2025

The following changes are planned but not yet deprecated:

| Feature | Deprecation Date | Sunset Date | Replacement |
|---------|------------------|-------------|-------------|
| Offset pagination (large datasets) | Q2 2025 | Q4 2025 | Cursor pagination |
| Legacy webhook format | Q3 2025 | Q1 2026 | Structured webhook payload |

---

## Deprecation Policy

### Timeline

```
Announcement → Deprecation → Sunset
    │              │            │
    │              │            └── Feature removed
    │              └── Deprecation warnings in responses
    └── 12 months before deprecation
```

### Minimum Notice Periods

| Phase | Minimum Notice |
|-------|----------------|
| Announcement to Deprecation | 12 months |
| Deprecation to Sunset | 6 months |
| Total lifecycle | 18+ months |

### Deprecation Indicators

When a feature is deprecated, you'll see:

#### Response Headers

```http
X-API-Deprecated: true
X-API-Deprecation-Date: 2025-06-01
X-API-Sunset-Date: 2025-12-01
Deprecation: true
Sunset: Mon, 01 Dec 2025 00:00:00 GMT
Link: <https://docs.tracertm.dev/migration/feature-name>; rel="deprecation"
```

#### Response Body (when applicable)

```json
{
  "data": {...},
  "warnings": [
    {
      "code": "DEPRECATED_FEATURE",
      "message": "The 'legacy_id' field is deprecated and will be removed on 2025-12-01",
      "documentation_url": "https://docs.tracertm.dev/migration/legacy-id",
      "sunset_date": "2025-12-01"
    }
  ]
}
```

---

## Deprecation Categories

### Endpoint Deprecations

When an endpoint is deprecated:

```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Mon, 01 Dec 2025 00:00:00 GMT
Link: <https://api.tracertm.dev/v1/items>; rel="successor-version"

{
  "data": {...},
  "warnings": [{
    "code": "DEPRECATED_ENDPOINT",
    "message": "This endpoint is deprecated. Use /v1/projects/{id}/items instead.",
    "replacement": "/v1/projects/{project_id}/items",
    "sunset_date": "2025-12-01"
  }]
}
```

### Field Deprecations

When a response field is deprecated:

```json
{
  "data": {
    "id": "item_req_001",
    "legacy_id": "12345",
    "_deprecated_fields": ["legacy_id"]
  },
  "warnings": [{
    "code": "DEPRECATED_FIELD",
    "field": "legacy_id",
    "message": "The 'legacy_id' field is deprecated. Use 'id' instead.",
    "sunset_date": "2025-12-01"
  }]
}
```

### Parameter Deprecations

When a query parameter is deprecated:

```bash
# Using deprecated parameter
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?legacy_filter=status:active"
```

Response:

```json
{
  "data": [...],
  "warnings": [{
    "code": "DEPRECATED_PARAMETER",
    "parameter": "legacy_filter",
    "message": "The 'legacy_filter' parameter is deprecated. Use 'filter' or 'status' instead.",
    "replacement": "status=active",
    "sunset_date": "2025-12-01"
  }]
}
```

### Behavior Deprecations

When default behavior changes:

```json
{
  "data": [...],
  "warnings": [{
    "code": "DEPRECATED_BEHAVIOR",
    "message": "Default sort order will change from 'updated_at desc' to 'created_at desc' on 2025-06-01",
    "current_behavior": "sort=updated_at&order=desc",
    "future_behavior": "sort=created_at&order=desc",
    "recommendation": "Explicitly specify sort parameters to avoid changes"
  }]
}
```

---

## Handling Deprecations

### Detecting in Code

#### Python

```python
from tracertm import TraceRTMClient

client = TraceRTMClient(api_key="rtm_live_sk_...")

# Enable deprecation warnings
client.config.warn_on_deprecation = True

# Get items with deprecation detection
response = client.items.list(project_id="proj_abc123")

# Check for warnings
if response.warnings:
    for warning in response.warnings:
        print(f"Warning: {warning.code} - {warning.message}")
        print(f"Sunset: {warning.sunset_date}")
        print(f"Docs: {warning.documentation_url}")
```

#### TypeScript

```typescript
import { TraceRTMClient } from '@tracertm/sdk';

const client = new TraceRTMClient({
  apiKey: 'rtm_live_sk_...',
  warnOnDeprecation: true
});

// Listen for deprecation warnings
client.on('deprecation', (warning) => {
  console.warn(`Deprecation: ${warning.code}`);
  console.warn(`Message: ${warning.message}`);
  console.warn(`Sunset: ${warning.sunsetDate}`);
});

// Or check response warnings
const response = await client.items.list({ projectId: 'proj_abc123' });
if (response.warnings?.length) {
  response.warnings.forEach(w => {
    console.warn(`${w.code}: ${w.message}`);
  });
}
```

#### Go

```go
package main

import (
    "fmt"
    "github.com/tracertm/tracertm-go"
)

func main() {
    client := tracertm.NewClient("rtm_live_sk_...",
        tracertm.WithDeprecationWarnings(true),
    )

    // Set deprecation handler
    client.OnDeprecation(func(warning tracertm.DeprecationWarning) {
        fmt.Printf("Deprecation: %s\n", warning.Code)
        fmt.Printf("Message: %s\n", warning.Message)
        fmt.Printf("Sunset: %s\n", warning.SunsetDate)
    })

    // Make request
    items, warnings, _ := client.Items.ListWithWarnings(ctx, "proj_abc123", nil)

    for _, w := range warnings {
        fmt.Printf("Warning: %s - %s\n", w.Code, w.Message)
    }
}
```

### Monitoring Deprecations

#### Webhook Notifications

Subscribe to deprecation webhooks:

```json
{
  "event": "api.deprecation.announced",
  "data": {
    "feature": "legacy_filter_parameter",
    "deprecation_date": "2025-06-01",
    "sunset_date": "2025-12-01",
    "affected_endpoints": ["/v1/projects/{id}/items"],
    "replacement": "filter parameter",
    "migration_guide": "https://docs.tracertm.dev/migration/legacy-filter"
  }
}
```

#### Email Notifications

Configure in Settings → API → Deprecation Notifications

Options:
- Immediate notification on new deprecations
- Weekly deprecation digest
- 30/60/90 day sunset reminders

---

## Deprecation History

### Resolved Deprecations

| Feature | Deprecated | Sunset | Replacement |
|---------|------------|--------|-------------|
| — | — | — | No resolved deprecations yet |

---

## Migration Resources

### Migration Checklist

When a deprecation is announced:

1. **Review Impact**
   - Check which endpoints/features you use
   - Review affected code paths
   - Estimate migration effort

2. **Plan Migration**
   - Read migration guide
   - Update to latest SDK (usually handles automatically)
   - Test in staging environment

3. **Execute Migration**
   - Deploy changes before sunset date
   - Monitor for issues
   - Remove deprecated code paths

4. **Verify Completion**
   - Confirm no deprecation warnings in logs
   - Update documentation
   - Close migration tasks

### SDK Auto-Migration

Many deprecations are handled automatically by SDK updates:

```python
# Old SDK (1.x) - uses deprecated endpoint
items = client.get_items(project_id)

# New SDK (2.x) - transparently uses new endpoint
items = client.items.list(project_id)  # Same result, new API
```

---

## Requesting Extensions

If you need more time to migrate, contact support:

1. **Email**: api-support@tracertm.dev
2. **Subject**: Deprecation Extension Request
3. **Include**:
   - Your organization/account ID
   - Feature needing extension
   - Current migration status
   - Requested extension period
   - Migration completion plan

Extensions are evaluated case-by-case and generally granted for:
- Enterprise customers with complex integrations
- Reasonable extension requests (30-90 days)
- Active migration progress demonstrated

---

## Status Page

Check current deprecation status:

- **Status Page**: https://status.tracertm.dev/deprecations
- **API Endpoint**: `GET https://api.tracertm.dev/v1/deprecations`

```bash
curl "https://api.tracertm.dev/v1/deprecations" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

Response:

```json
{
  "deprecations": [],
  "upcoming": [
    {
      "feature": "offset_pagination_large_datasets",
      "announcement_date": "2024-06-01",
      "deprecation_date": "2025-06-01",
      "sunset_date": "2025-12-01",
      "status": "announced",
      "affected_endpoints": ["/v1/projects/{id}/items"],
      "migration_guide": "https://docs.tracertm.dev/migration/cursor-pagination"
    }
  ],
  "resolved": []
}
```

---

## Related Documentation

- [API Versioning](/docs/api-reference/rest-api/versioning) - Versioning strategy
- [API Versions](/docs/api-reference/rest-api/api-versions) - Version changelog
- [Migration Guide](/docs/api-reference/rest-api/migration-guide) - Migration instructions
