Versioning

Understand how API versions work and how to stay compatible.

Current Version

Current API Version

2026-02-01 — This is the only version currently available.

Version Headers

Every API response includes version information in the headers:

Header	Description	Example
`X-EZToTrack-Version`	The API version used for the response	`2026-02-01`
`X-EZToTrack-Supported-Versions`	All currently supported versions	`2026-02-01`

HTTP/1.1 200 OK
Content-Type: application/json
X-EZToTrack-Version: 2026-02-01
X-EZToTrack-Supported-Versions: 2026-02-01
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9

Version Format

API versions use date-based identifiers in YYYY-MM-DD format. Each version represents a stable snapshot of the API contract. New versions are released when breaking changes are introduced.

Compatibility Policy

Non-breaking changes (no new version)

The following changes are considered backwards-compatible and may be made without a new version:

Adding new endpoints
Adding new optional query parameters
Adding new fields to response objects
Adding new enum values
Adding new webhook event types

Important

Your code should be resilient to new fields appearing in responses. Always ignore unknown fields rather than treating them as errors.

Breaking changes (new version required)

The following changes require a new API version:

Removing or renaming endpoints
Removing or renaming response fields
Changing the type of a response field
Changing required query parameters
Changing authentication requirements
Changing error response formats

Deprecation Policy

When a new API version is released:

The previous version enters a deprecation period of at least 12 months
Deprecated versions will include a Sunset response header with the retirement date
A notice will be posted in the Changelog
After the sunset date, deprecated versions will return 410 Gone

Migration Guide

When a new version is released, we will publish a migration guide detailing:

All breaking changes and their rationale
Before/after code examples
Step-by-step migration instructions
Timeline for deprecation of the old version

Stay Updated

Monitor the Changelog for version announcements and breaking change notifications.