Developer portal

API versioning & deprecation policy

How the QEHS public API evolves without breaking your integration.

Policy at a glance

Versioning scheme: Semantic versioning (semver). Major versions live at /api/v1, /api/v2, …
Deprecation window: 12 months minimum from announcement to removal.
Sunset notice: 6 months before sunset, email + in-app banner to tenant admins.
Prior major support: 24 months after the next major ships.

What counts as breaking

Additive changes are not breaking and can ship any time. The following require a deprecation cycle:

Removing an endpoint, field, enum value, or query parameter.
Narrowing an accepted input (tightening validation, making a field required).
Changing the type of a response field.
Changing HTTP status-code semantics on existing paths.
Renaming a resource or changing its URL shape.

Deprecation signals your code can detect

Every deprecated endpoint advertises itself three ways. All three follow RFC 8594 and the IETF HTTP API Deprecation draft.

A Deprecation header (HTTP-date) on every response from the deprecated endpoint.
A Sunset header (HTTP-date) naming the removal date, again on every response.
A Link: <url>; rel="deprecation" header pointing at the migration guide.

Our published SDKs surface these as warnings automatically. Hand-rolled clients should log + escalate when they appear.

Machine-readable deprecation index

Poll this endpoint nightly to catch upcoming sunsets before they affect you.

GET https://app.qehsethos.com/api/public/deprecations.json

View deprecations.json

Response shape is versioned via schemaVersion. New fields on entries are additive; shape changes create a new schemaVersion.

Migration guides

Every deprecation links to a side-by-side migration guide in the changelog.

Browse the API changelog →

Subscribe to breaking-change alerts

Tenant admins and API-key owners receive emails at deprecation, 6 months before sunset, 1 month before, and on sunset day. RSS is available at /developers/changelog/rss.xml.