API Versioning and Deprecation
The REST API uses the /v1 path prefix, except for protocol endpoints and URLs that must stay stable across API versions. This page explains which routes stay at the root and how OpenTremor handles breaking changes.
curl -H "X-API-Key: $KEY" https://api.example.com/v1/orgsThe interactive reference is at /v1/docs, and the schema is at /v1/openapi.json.
Routes at the root
Section titled “Routes at the root”These routes stay at the root so they remain stable across API versions. Some are fixed by a protocol, stored by a third party, or included in links that have already been shared.
| Route | Why it stays at the root |
|---|---|
/health, /health/ready | Liveness and readiness probes used by deployments and load balancers |
/metrics | Prometheus scrape target |
/network-access/verdict | Its full URL is stored in deployment configuration |
/integrations/github/webhook, /integrations/github/manifest/callback | Registered in the GitHub App |
/integrations/gitlab/webhook/{webhook_id} | Registered in each GitLab project hook |
/auth/sso/callback | Registered at each organization’s OIDC identity provider |
/auth/sso/saml/{org_id}/metadata, /auth/sso/saml/{org_id}/acs, /auth/sso/saml/complete | Used by each organization’s SAML identity provider |
/auth/oauth/{provider}/callback | Registered in the Google and Microsoft OAuth apps |
/notifications/slack/callback | Registered in the Slack app |
/scim/v2/{org_id}/… | SCIM has its own versioned path |
/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize, /oauth/token | OAuth discovery and protocol routes for MCP clients |
/reports/{token} | Public report links already posted in pull requests |
A new API version leaves these URLs unchanged. Integrations do not need to register them again.
What changes within v1
Section titled “What changes within v1”Changes within v1 are additive:
- New routes
- New optional request fields
- New response fields
- New enum values
Clients must ignore response fields they do not recognize and accept enum values they have not seen.
How OpenTremor handles breaking changes
Section titled “How OpenTremor handles breaking changes”A breaking change ships under /v2. /v1 keeps running for at least 6 months after /v2 becomes generally available. Deprecated routes return a Deprecation header (RFC 9745) and a Sunset header with the removal date (RFC 8594).
- The changelog lists every deprecated route.
OpenTremor freezes v1 at general availability. Until then, v1 follows the additive-change policy above.