Current versions
Public API: v1
All endpoints under /api/v1/*.
Platform
API versioning and lifecycle policy
The API uses URL-based versioning. Breaking changes are introduced under a new URL prefix.
Current versions
SCIM API: v2
All endpoints under /scim/v2/* (SCIM 2.0 standard).
Current versions
WebSocket API
Unversioned. Uses the same auth and data models as REST.
Non-breaking vs breaking changes
Non-breaking (added anytime)
New endpoints, new optional request parameters, new response fields, new event types for webhooks, new enum values (existing values remain valid).
Non-breaking vs breaking changes
Breaking (requires new version)
Removing or renaming endpoints or fields, changing field types, removing enum values, changing authentication requirements.
Details
Deprecation policy
Sunset process
1) A Deprecation: true response header is added. 2) A Sunset header indicates the removal date. 3) A Link header points to the migration guide. 4) The deprecated endpoint continues to function for at least 6 months. 5) After the sunset date, the endpoint returns HTTP 410 (Gone).
Details
Migration support
Guarantees
When a new API version is released: the previous version operates for at least 12 months, migration guides are published 6 months before sunset, breaking changes include before/after examples, and the OpenAPI spec for each version remains available.
Related docs