Versioning and Breaking Changes

Admin and Management
  • Updated on Oct 21, 2025
  • Published on Oct 20, 2025
  • 2 minute(s) read
Prev Next

This page contains information about how we version our APIs and our stance on managing potentially disruptive updates.

At Thrive we are committed to delivering new capabilities without disrupting your existing integrations. This page explains how we version our APIs, what constitutes a breaking change, and how we communicate and support transitions when new versions are released.

How We Version Our APIs

Thrive uses URI Versioning, meaning each API version appears directly in the request path.

For example, our current version is v1, so the path looks like this:

https://public.api.learn.link/rest/v1/users

When we introduce a new version, it will be released under a distinct path, such as v2:

https://public.api.learn.link/rest/v2/users

This approach ensures existing integrations remain stable and unaffected while you plan your upgrade.

When We Release a New Version

We introduce a new API version only when:

  • A breaking change is required (something that could impact existing integrations), or

  • We’re adding major new functionality that warrants a distinct version.

Whenever a new version is released:

  • The previous version is immediately deprecated, following our deprecation policy (typically given with 3 months notice).

  • You’ll receive notifications via email, changelog, and your account director if applicable.

  • Migration guidance will be provided to help you move to the latest version smoothly.

What Counts as a Breaking Change

A breaking change is any update that could cause existing API calls to fail, behave differently, or require client-side updates. Examples include:

  • Removing or renaming an endpoint.

  • Changing the structure or meaning of a response field.

  • Making a required field optional or an optional field required.

  • Changing data types or validation rules.

  • Modifying authentication or permission models.

While we strive to avoid them, breaking changes are sometimes necessary. We’ll always release them in a new version and give you plenty of notice.

What’s Not a Breaking Change

Certain updates can safely happen within the same version, as they will not disrupt existing integrations:

  • Adding new, optional fields or endpoints.

  • Extending enumerated (enum) values or accepted parameters.

  • Adding new response properties that can be safely ignored.

  • Performance or documentation improvements.

  • Bug fixes that don’t alter API contracts.

These are released under the same version and announced in the changelog.

Communication and Transparency

You’ll always be notified when a new version or breaking change is released. We’ll communicate to you via:

  • Email notifications.

  • Posts on the Thrive Tribe community forum.

  • Direct contact from your account director.

Each notice will include:

  • The affected version(s).

  • The release date and deprecation start date.

  • Migration guidance and updated documentation links.

Developer Guidance

To make version management easier:

  • Pin your version: Always specify the version in your API calls (e.g., .../v1/...) to avoid unintentional updates.

  • Monitor the changelog: Stay up to date with non-breaking updates and new releases.

  • Test in advance: When a new version is released, use a staging or sandbox environment before upgrading your production integration.

  • Plan for version lifecycles: Expect each version to have an active and a deprecation period, as detailed in our deprecation policy.

  • Use version variables: Store the API version in environment configuration to simplify future upgrades.

Need Help Upgrading?

If you need help or support when upgrading to a new API version, please initially contact our Support team. We’ll make sure your migration is smooth, safe, and well-supported.