Our API uses a date-based versioning scheme in the format YYYY-MM-DD.
Each new version release indicates breaking changes that are not backwards compatible and may affect
existing integrations.
When a new version is released, you may continue using the previous version for 2 years, after which your
version will automatically be upgraded. We strongly recommend upgrading manually in advance to avoid
unexpected disruptions.
We will send reminders at 1 year and again at 3 months before your current version becomes unsupported.
Around 2 months before version retirement we run a brief brownout.
Managing your version
You can view your current API version, upgrade to newer versions, and access changelogs directly in
your API settings within Skovik.
- Changelogs are also available here, under the Changelog tab.
Once upgraded, it's not possible to downgrade.
Selectively enabling a new version
Before upgrading, you can selectively enable a new version with the X-Api-Version request header. Note that cannot be older than your company's current version though.
For example: X-Api-Version: 2025-09-30
Use this header while testing a new API version, or for a short period during a migration to a new version. Once you've verified that it works, make sure you upgrade the account API version via the UI.
Selectively enabling a version via HTTP headers should not be a permanent mechanism to do a version upgrade.
Backwards-compatible changes
Certain changes that are considered backward-compatible will not require a new version.
A well behaving client should have no problem with these, but for clarity they are spelled out below:
- Adding new API resources.
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses.
- Changing the order of properties in existing API responses.
- Changing the length or format of resource IDs or other opaque strings.
- You can assume resource IDs will never exceed 255 characters (you must be able to handle IDs up to that length).
- Endpoints moved via HTTP redirects, in other words your HTTP client should follow redirects.
Deprecation and Sunset HTTP response headers
The Deprecation header indicates that your API version is deprecated or scheduled for deprecation.
Its value is a Structured Fields Date (number of seconds since the Unix epoch) prefixed with an @:
Deprecation: @1735689600The example above is 2025-01-01T00:00:00Z. The deprecation header date may be in the future or the past.
The Sunset header tells you when your version is retired. Its value is an HTTP date:
Sunset: Wed, 01 Oct 2025 00:00:00 GMTIf your integration logs or inspects response headers, watching for these two is an automated signal that an upgrade is due.