Skip to content

Api change policy

API Versioning

The Firstbeat Sports Cloud API uses URL versioning, where the API version is included in the base URL.

https://api.firstbeat.com/v1/

Supported API Versions

Only one API version (the latest) is officially supported at any given time. Bug fixes and new features are applied to the latest version only. Older versions may remain accessible but are not actively maintained.

End-of-Life for Old API Versions

End-of-life announcements for API versions will be published in this documentation and communicated via email. The standard notice period is 12 months before an API version is retired.

In exceptional circumstances—such as critical security vulnerabilities or major issues requiring significant resources to fix—Firstbeat Sports reserves the right to announce shorter retirement periods.

Upgrading to New Versions

Before upgrading to a new API version, it's essential to read the changelog of breaking changes for the new API version. This will help you understand what breaking changes are included and learn more about how to upgrade to that specific version.

Always test any changes thoroughly before migrating to a new version.

Breaking Changes

The following changes are considered breaking and will only be introduced in new API versions:

  • Removing or renaming an endpoint
  • Removing or renaming a parameter
  • Adding new required parameters
  • Changing data format types
  • Changing authentication requirements

Non-breaking Changes

Important

API clients should be designed to ignore unknown response fields to maintain compatibility with non-breaking changes.

The following changes may be introduced within the same API version:

  • Adding a new endpoint or operation
  • Adding an optional parameter
  • Adding a parameter for alternative response formats (e.g., responseFormat=v2)
  • Adding an optional request header
  • Adding a response field (consumers should ignore unknown fields)
  • Adding a response header
  • Adding or removing analysis result variables (scalars or time series)
  • Making a previously required response field optional
  • Changes to rate limits or daily quotas (these are configurable for each API consumer)