API versioning and deprecation

Exhale’s canonical public HTTP API is under /v1.

Surface	Example	Status
Versioned (canonical)	GET /v1/pulses, POST /v1/webhooks/pagerduty	Supported
Unversioned aliases	GET /pulses, POST /webhooks/pagerduty	Compatibility — same handlers as /v1

Browser apps call same-origin /api/.... Hosted nginx strips the /api prefix before FastAPI, so the paths in this documentation are the FastAPI paths (/v1/...).

Staff/ops routes (/internal/*, /ops/*, /metrics) are not versioned under /v1 and are not part of the public integrator contract.

Deprecation policy

1. Breaking changes to /v1 (removed fields, changed auth, removed routes) require a notice period of at least 90 days in the changelog before removal, unless a security issue forces a shorter window.
2. Unversioned aliases may be removed after the same notice period once integrators have migrated to /v1. Until then they remain functional.
3. Additive changes (new optional fields, new routes under /v1) do not require a notice period.
4. When a future major version ships (/v2), /v1 remains available until its published sunset date.

Headers (future)

Exhale may add deprecation response headers (for example Deprecation / Sunset) when retiring a specific path. Until those ship, the changelog is the source of truth.

See also

• API reference — OpenAPI for /v1
• Errors & authentication