> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edpire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning & Change Policy

> How Edpire versions its API, classifies changes, and communicates updates to integration partners.

**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:

```
https://edpire.com/api/v1/...
https://edpire.com/api/v2/...
```

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](/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

| Change type                    | How you'll be notified                         |
| ------------------------------ | ---------------------------------------------- |
| Non-breaking changes           | Changelog at `docs.edpire.com/changelog`       |
| Breaking changes / deprecation | Email to all API key holders + Changelog entry |
| Security patches               | Email after deployment + Changelog entry       |
| Planned maintenance            | Email to account contact (48h advance notice)  |

**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](mailto:support@edpire.com) to register additional addresses.

***

## Version Lifecycle Summary

| Phase           | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| **Current**     | Fully supported, receives non-breaking improvements                          |
| **Deprecated**  | Announced for end-of-life, still fully functional, migration guide available |
| **End-of-life** | Returns `410 Gone`, no longer functional — migration required                |

***

## 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](/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](mailto:support@edpire.com). We will do our best to accommodate longer migration windows for established clients.

***

*Edpire — [support@edpire.com](mailto:support@edpire.com)*