API Versioning
How the HEIR API handles versioning and deprecation.
Current Version
The current API version is v1. All endpoints are prefixed with /api/v1/.
https://api.heir.es/api/v1/Version Header
The response includes the API version:
http
X-API-Version: v1Legacy Endpoints
Deprecation Notice
Endpoints without version prefix (/api/*) are deprecated and will be removed on July 1, 2026.
Legacy requests return deprecation headers:
http
X-API-Deprecation: true
X-API-Sunset: 2026-07-01T00:00:00ZMigration Guide
Before (deprecated)
bash
curl https://api.heir.es/api/contracts/generateAfter (current)
bash
curl https://api.heir.es/api/v1/contracts/generateBreaking Changes Policy
We follow semantic versioning principles:
- Major version (v1 → v2): Breaking changes
- Minor updates: New features, backward compatible
- Patches: Bug fixes
What's Considered Breaking
- Removing endpoints
- Removing required request fields
- Changing response structure
- Changing authentication methods
- Reducing rate limits significantly
What's Not Breaking
- Adding new endpoints
- Adding optional request fields
- Adding new response fields
- Increasing rate limits
- Adding new error codes
Version Lifecycle
| Status | Description | Support |
|---|---|---|
| Current | Latest stable version | Full |
| Deprecated | Scheduled for removal | Bug fixes only |
| Sunset | Removed | None |
Notification Policy
Before any breaking change:
- 6 months notice via deprecation headers
- Email notification to all API key holders
- Documentation updates with migration guides
- Sunset date in
X-API-Sunsetheader
Staying Updated
Subscribe to API updates: