Skip to content
DashboardWebsite

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.

Terminal window
curl -H "X-API-Key: $KEY" https://api.example.com/v1/orgs

The interactive reference is at /v1/docs, and the schema is at /v1/openapi.json.

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.

RouteWhy it stays at the root
/health, /health/readyLiveness and readiness probes used by deployments and load balancers
/metricsPrometheus scrape target
/network-access/verdictIts full URL is stored in deployment configuration
/integrations/github/webhook, /integrations/github/manifest/callbackRegistered in the GitHub App
/integrations/gitlab/webhook/{webhook_id}Registered in each GitLab project hook
/auth/sso/callbackRegistered at each organization’s OIDC identity provider
/auth/sso/saml/{org_id}/metadata, /auth/sso/saml/{org_id}/acs, /auth/sso/saml/completeUsed by each organization’s SAML identity provider
/auth/oauth/{provider}/callbackRegistered in the Google and Microsoft OAuth apps
/notifications/slack/callbackRegistered in the Slack app
/scim/v2/{org_id}/…SCIM has its own versioned path
/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize, /oauth/tokenOAuth 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.

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.

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.