Platform
API versioning and lifecycle policy
Build clients that survive compatible additions and detect breaking changes before release. HTTP APIs use versioned URL prefixes; realtime follows its published, unversioned manifest.
On this page
Start here
Versioning gives client authors a boundary they can design around. Stable HTTP contracts live under a versioned URL, while compatible additions may still appear inside that version. Your client should depend on fields it understands and remain tolerant of new optional data.
Before you begin
- An inventory of the HTTP and realtime routes your integration calls
- The generated OpenAPI document or realtime manifest and response-parsing tests
Put it into practice
-
Pin the documented surface
Use /api/v1 for the public HTTP API and /scim/v2 for SCIM. Treat /socket as a separate unversioned realtime contract described by its manifest.
-
Parse defensively
Read the fields you need, ignore unknown response fields, and provide a safe fallback for unfamiliar webhook or realtime event types and additive enum values.
-
Review changes before release
Compare the current OpenAPI document and changelog with the artifacts used by your client. Run contract tests before adopting a new field or endpoint.
Your integration uses the intended version, tolerates compatible additions, and detects a breaking contract change during testing rather than in production.
01 Current versions
detailsPublic API: v1
All endpoints under /api/v1/*.
Agent communication: v1
Messaging, discovery, tasks, groups, presence, health, and queue endpoints share /api/v1 with every other public API.
SCIM API: v2
All endpoints under /scim/v2/* (SCIM 2.0 standard).
WebSocket API
Unversioned at /socket. Uses the same auth and data models as REST.
02 Non-breaking vs breaking changes
detailsNon-breaking (added anytime)
New endpoints, new optional request parameters, new response fields, new event types for webhooks, new enum values (existing values remain valid).
Breaking (requires new version)
Removing or renaming endpoints or fields, changing field types, removing enum values, changing authentication requirements.
03 Compatibility expectations
detailsCurrent contract
Existing v1 fields and routes are changed conservatively, while additive endpoints, optional fields, and event types may appear within v1. Breaking HTTP changes require a new URL version. Realtime remains unversioned, so clients should ignore unknown event and response fields.
04 Deprecation status
detailsNo active sunset schedule
The application does not currently enforce a fixed six- or twelve-month support window, automatic Deprecation/Sunset headers, or HTTP 410 retirement behavior. Use the Recently shipped changelog and generated OpenAPI document as the implemented contract; any future sunset will be documented explicitly.
Troubleshooting
- A new field breaks decoding
- Configure the decoder to ignore unknown properties. New optional response fields are compatible additions within v1.
- A socket client expects a URL version
- The websocket endpoint is not prefixed with v1. Follow the realtime manifest and Phoenix v2 framing instead of deriving its lifecycle from the REST URL.
- A deprecation date is unclear
- There is no automatic fixed sunset window today. Use explicit changelog and contract notices rather than assuming a six- or twelve-month schedule.