Skip to main content
Effective date: 2026-05-01 This document defines how Edpire manages changes to its public API — what constitutes a breaking change, how long deprecated versions remain alive, and how clients are notified.

​
Versioning Scheme

The Edpire REST API is versioned via URL path prefix:
The current stable version is v1. A new major version is only introduced when breaking changes are unavoidable. Minor and patch-level improvements are deployed to the current version without a version bump. Breaking changes go to the next major version, not to the current one. If a change would break existing integrations, it ships in a new major version and the old one is kept alive through the deprecation period. The one exception is a security fix, which may change behavior immediately (see Security Patches below).

​
Change Classification

​
Non-Breaking Changes

The following changes are deployed to the current version without advance notice. They will not break existing integrations:
  • New endpoints added to the API
  • New optional fields added to existing request bodies
  • New fields added to existing response objects
  • New webhook event types
  • New optional query parameters
  • Performance improvements and internal refactors
  • Bug fixes that make behavior match the documented spec
Non-breaking changes are listed in the Changelog.

​
Breaking Changes

The following require a new major version and a full deprecation cycle:
  • Removing or renaming an endpoint
  • Removing or renaming a field in a request or response
  • Changing the type or format of an existing field
  • Making a previously optional field required
  • Changing authentication or authorization behavior
  • Removing a webhook event type
  • Changes to the ContentAST schema (assessment/exercise data format) that alter how existing content is parsed

​
Security Patches

Security vulnerabilities are patched immediately without advance notice, even if the fix changes behavior. Clients are notified after the patch is deployed with a description of the issue and the fix applied.

​
Deprecation Process

When a breaking change requires a new API version:
  1. Announcement: Edpire emails all API key holders at least 60 days before the migration deadline. The email includes what is changing, why, a migration guide, and the exact deadline.
  2. Parallel operation: Both versions run in parallel throughout, and the old version stays alive for a further 60 days after the announced deadline. In total you have a minimum of 120 days from announcement before the old version stops working.
  3. Reminder: A second email is sent 14 days before the deadline.
  4. End of life: After the grace period, the old version returns 410 Gone with a message pointing to the migration guide. It is not silently removed.
For changes with significant migration complexity, Edpire may extend these periods and will communicate the longer timeline upfront.

​
ContentAST Versioning

The ContentAST schema — the JSON format used for assessment and exercise content — follows the same breaking change policy as the REST API. Changes to ContentAST that would alter how existing content is interpreted are treated as breaking changes and follow the full deprecation process above. Our intent is that you never need to migrate stored assessment data, and any change that would require it is announced through that process rather than deployed silently.

​
Communication Channels

To ensure you receive notifications: Keep the contact email on your Edpire account up to date. API key holders are the primary notification target. If multiple team members should receive API change notices, contact support@edpire.com to register additional addresses.

​
Version Lifecycle Summary

​
SDK Versioning

The @edpire/sdk package is currently pre-1.0. Under semver, that means minor releases may contain breaking changes, and we recommend pinning an exact version rather than a range. SDK changes are listed in the Changelog. Once the SDK reaches 1.0, breaking changes will be released as major version bumps under the same notice period as the REST API. The REST API’s stability guarantees apply today regardless of SDK version: pinning an older SDK does not put you on an older API.

​
Requesting Advance Notice

If you have a large integration and need more than 60 days lead time for a specific upcoming change, contact support@edpire.com. We will do our best to accommodate longer migration windows for established clients.
Edpire — support@edpire.com