CommentKit / Reference

Versions and changes

Additive-only v1, 12 months of notice, 24 months of support and how to pin a version.

What stays the same

Version 1 of the API (/api/v1) and the widget only grow. New fields, new endpoints, new error codes and new optional parameters can appear at any time, so ignore fields you do not know. Nothing you rely on today is renamed, removed or changes meaning within v1.

A change that could break working code (removing a field, making an optional field required, changing what a value means) only happens in a new major version, such as /api/v2 or widget 2.x. The old version keeps working next to it.

Notice before anything is removed

When something is going away, you get at least 12 months’ notice before it stops working. During that time it keeps working exactly as before. The change is announced in the release notes and by email to workspace owners.

How you are told

Responses from an API endpoint that is on its way out carry two standard headers, so your monitoring can spot them without reading release notes:

Deprecation (RFC 9745): when the endpoint was marked as going away, as a timestamp such as @1798761600.
Sunset (RFC 8594): the date after which it may stop working, at least 12 months later.
Link with rel="deprecation" pointing at what to use instead.

Example response headers

Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://commentkit.dev/docs/versioning>; rel="deprecation"

No endpoint is deprecated today.

How long each version is supported

Every major version of the API and of the widget (the @commentkit/comment-kit package and the script tag) gets 24 months of long-term support after the next major version is released. During that time it gets security and reliability fixes, and the API keeps answering it.

Pin a version

The script tag at /cdn/v1/loader.js always serves the newest 1.x release, so you get fixes without doing anything and never a breaking change. To stay on one exact release, use the versioned address and integrity hash from that release’s notes (see Subresource Integrity).

With npm, install one full version number (from the release notes or npm view @commentkit/comment-kit versions) and commit your lockfile:

Terminal

npm install --save-exact @commentkit/[email protected]

Or let npm take new 1.x releases with a range such as ^1.5.0. That is safe because 1.x never breaks.