Versioning and deprecation

The API is versioned in the URL path. The stable production version is v1:

https://app.syncro.chat/api/v1

Every integration should pin the version explicitly in the URL. There is no header-based version negotiation and no "unversioned" URL that follows the latest release — this is deliberate: an integration never changes behaviour on its own.

These changes only ship in a new version (v2, v3…):

• Removing or renaming an endpoint, a response field or a parameter
• Making a previously optional parameter required
• Changing a field's type, or the HTTP status returned for an already documented case
• Changing the meaning of an existing value

These changes are backwards compatible and may land in v1 without notice — your integration must tolerate them:

• Adding a new endpoint
• Adding a new field to a response
• Adding an optional parameter
• Adding a new value to an existing enum
• Fixing behaviour that diverged from the documentation

When an endpoint or a version is deprecated, the notice travels in the HTTP response itself, so an automated client notices without relying on email or a changelog:

Header	Content
Deprecation	The date the deprecation took effect (HTTP-date), per RFC 9745
Sunset	The date the resource stops responding (HTTP-date), per RFC 8594
Link	rel="deprecation" pointing at the documentation for the replacement

Example:

HTTP/1.1 200 OK
Deprecation: Wed, 01 Oct 2026 00:00:00 GMT
Sunset: Sun, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.syncro.chat/en/versioning>; rel="deprecation"

Commitments:

• At least 6 months between Deprecation and Sunset.
• An entire API version is only switched off after at least 12 months notice.
• The deprecated operation is also flagged deprecated: true in the OpenAPI specification, so your CI can detect the change automatically.
• Nothing is removed before a documented replacement exists.

• Watch the Deprecation and Sunset headers on responses — it is the most reliable channel.
• Periodically diff the OpenAPI specification against the version you integrated against; it is generated from this documentation and reflects the current state.
• The x-deprecation-policy object at the root of the specification points back to this page.