API Versioning & Deprecation Policy

1. Versioning Scheme

The TrackLogy REST API uses URL path versioning. The current stable version is v1, served at:

https://api.tracklogy.com/v1

All endpoints documented in the OpenAPI 3.1 specification and API reference are stable within the current version.

2. Stability Guarantee

Within a major version (v1), TrackLogy commits to:

• No removal of existing endpoints
• No removal of existing request or response fields
• No change to existing field types or enum values
• No changes to authentication requirements for existing endpoints

Additive changes (new endpoints, new optional fields, new enum values) may be made at any time without notice and are not considered breaking.

3. Deprecation Process

When TrackLogy deprecates an endpoint or field, we follow this process:

3.1 Announcement

Deprecations are announced via email to registered API key holders, in the developer changelog, and in the OpenAPI specification using the deprecated: true flag.

3.2 Response Headers

Deprecated endpoints return machine-readable headers on every response:

Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://docs.tracklogy.com/api-reference>; rel="successor-version"

• Deprecation — signals the endpoint is deprecated (RFC 8594)
• Sunset — the date after which the endpoint will no longer be available (RFC 8594)
• Link — points to the successor endpoint or migration guide

3.3 Minimum Notice Period

TrackLogy guarantees a minimum of 12 months between a deprecation announcement and the Sunset date for any endpoint or field. For endpoints used by more than 5% of active integrations, the minimum is 18 months.

3.4 Removal

After the Sunset date, removed endpoints return 410 Gone for a further 90 days before the route is retired entirely, so agents that check status codes receive a clear signal rather than a network error.

4. Rate Limits

The API returns standard rate-limit headers on every authenticated response:

RateLimit-Limit: 600
RateLimit-Remaining: 598
RateLimit-Reset: 1756147200

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

5. New Versions

When TrackLogy introduces a new major API version (e.g., v2), the previous version continues to be supported for at least 24 monthsfrom the new version's general availability date. Both versions are served simultaneously during this period.

6. Questions

Questions about API versioning or deprecation timelines? Contact us or email [email protected].