API versioning and lifecycle

Zentalk versions its REST API in the URL path; the current stable version is v1, served under https://api.zentalk.chat/api/v1/. The original unversioned API (/api/*) is deprecated but still served — all new integrations must use /api/v1/*.

API generations

Generation	Base path	Status	Released
v1	/api/v1/	Active (stable)	2025-01-01
Unversioned (legacy)	/api/	Deprecated (still served)	2024-11-01

Every v1 route is registered under both prefixes, so legacy integrations keep working unchanged; unversioned responses carry deprecation headers (Deprecation: true, a Sunset date, and a Link to the successor version). No retirement date is enforced yet — retirement will follow the lifecycle policy below.

v1 is fully compatible with the legacy unversioned API — migrating means updating the base URL, nothing else:

Migrating from the unversioned API

// Before (deprecated)
const baseURL = "https://api.zentalk.chat/api";

// After (v1)
const baseURL = "https://api.zentalk.chat/api/v1";

For the full endpoint catalog, see the REST API reference. Authentication is unchanged across generations; see Authentication.

Versioning scheme

The version appears as a path segment:

https://api.zentalk.chat/api/{version}/{resource}

• Major versions (v1, v2, …) contain breaking changes: removed or renamed fields, changed data types, removed endpoints, or changed authentication mechanisms. Each major version gets a new path prefix.
• Minor updates are non-breaking additions (new endpoints, new optional parameters, new response fields) and ship within the current major version without a path change.
• Patch updates (bug fixes, security patches) are transparent to clients.

Within a major version, the API never removes or renames existing fields, never changes data types, and never removes endpoints.

Version headers

Every response includes the version that served it, and clients may optionally request a version via the Accept header:

Accept: application/vnd.zentalk.v1+json

HTTP/1.1 200 OK
X-API-Version: v1
X-API-Stability: stable

Version discovery

Query the versions the server supports:

GET /api/version

{
  "success": true,
  "data": {
    "version": "v1",
    "deprecated": false,
    "supported_versions": ["v1"],
    "current_path": "/api/v1/"
  }
}

Lifecycle states

Each API version moves through a defined sequence of states, advertised in the X-API-Stability response header.

State	Access	Breaking changes	Support
Development	Internal only	Frequent	None
Alpha	Select partners (/api/v2-alpha/)	Possible	Limited
Beta	Public (/api/v2-beta/)	Possible with notice	Standard
Stable	Public (/api/v1/)	Never	Full, SLA-backed
Deprecated	Public, unchanged behavior	Never	Critical bug fixes and security patches only
Sunset	Public, 30–90 days before retirement	Never	Critical security patches only
Retired	None — requests return 410 Gone	—	None

New major versions are available in beta for at least 3 months before the previous version is deprecated.

Deprecation policy

• 12-month notice. A deprecation is announced at least 12 months before the sunset date, via the changelog, developer newsletter, and documentation.
• 12-month minimum support. A major version remains supported for at least 12 months after its successor’s stable release.
• Security patches are applied to all supported versions; bug fixes are applied to the current and previous major version.

While a version is deprecated, every response carries deprecation headers. Illustrative example of a hypothetical future v1 deprecation:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v2/>; rel="successor-version"
X-API-Version: v1

After the sunset date passes and a version is retired, requests to it fail with 410 Gone. No version has reached this state yet; the example below illustrates what a future retirement of the unversioned API would look like:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "The unversioned API has been retired",
  "retired_on": "2027-06-30",
  "successor": "/api/v1/",
  "documentation": "https://developer.zentalk.chat/reference/versioning/"
}

Client guidance

• Always call versioned endpoints (/api/v1/*); never rely on unversioned paths.
• Log the X-API-Version header and watch for Deprecation: true so migrations surface early:

Detecting deprecation at runtime

const response = await fetch('https://api.zentalk.chat/api/v1/messages', {
  headers: { Authorization: `Bearer ${token}` },
});

if (response.headers.get('Deprecation') === 'true') {
  console.warn(
    `API deprecated. Sunset: ${response.headers.get('Sunset')}. ` +
    `Successor: ${response.headers.get('Link')}`
  );
}

• Test against beta versions when they are announced, and subscribe to the changelog for breaking-change notices.