API Versioning
All API requests are versioned using the major version, prefixed by a v in the URL path (e.g. v1, v2). The latest and recommended version is v2. The version in the URL only changes when we introduce breaking changes; backward-compatible improvements, such as bug fixes, new endpoints, and new fields, are released continuously within the same major version.
https://api.apivoid.com/v2/{service}Backward-compatible changes
The following changes are considered non-breaking and can be released at any time within the current major version, without a new versioned URL. Your integration should be built to tolerate them:
- Adding new API endpoints (services).
- Adding new optional request parameters.
- Adding new fields to JSON responses.
- Changing the order of fields within JSON responses.
- Adding new HTTP response headers.
Build a tolerant parser: read the fields you need and ignore any you do not recognize. Fields that are not documented on these pages are pre-release, and may be renamed, changed, or removed at any time without notice, so do not depend on them in production. This helps keep your integration resilient as the API evolves.
Breaking changes
The following changes are considered breaking and are only introduced with a new major version (e.g. v2 → v3), released under a new versioned URL endpoint to avoid disrupting existing integrations:
- Removing or renaming documented JSON response fields.
- Changing the data type or meaning of a documented field.
- Removing request parameters, or making optional parameters required.
- Removing or renaming API endpoints.
- Changing the authentication method or the error response format.
Deprecation policy
When we release a new major API version, the previous version is deprecated but remains fully operational for at least 6 months from the announcement date, giving you time to migrate at your own pace. After the announced end-of-life date, deprecated endpoints may be shut down and stop responding at any time.
Recommendation: always integrate against the latest major version (currently at v2) and follow the changelog to stay informed about new features and announcements, including API enhancements, newly available endpoints, important behavioral changes, deprecations, migration guidance, and other updates that may affect your integration.
When a new major version is announced, we will:
- Notify all registered users via our newsletter, including the end-of-life date of the deprecated version.
- Publish the announcement and migration notes on our changelog.
- Update these documentation pages with the new version's reference and a migration guide.