Versioning

Two layersCopy Anchor Link

The path carries the major version: /v2/.... A new major version is a new path, and the old one keeps working. /v1 is frozen: it gets security fixes only, and new work lands on /v2.

The Gauge-Version header carries a dated version for changes inside /v2:

Gauge-Version: 2026-10-21

• Leave it out and you get the current version. Fine while you build.
• Send it in production to pin the behaviour your code was written against.
• An unknown value answers 400 validation_failed rather than silently using another version, so a typo cannot change behaviour without you noticing.
• Every /v2 response echoes the version it followed in its own Gauge-Version header.

Published versions: 2026-10-21 (current).

What counts as a breaking changeCopy Anchor Link

These are additive and can ship at any time, without a new version. Write your client to tolerate them:

• a new endpoint, or a new optional request field or query parameter;
• a new field in a response object;
• a new value in an enum we document as extensible (event names, error.reason, connection kind);
• a new webhook event type.

These are breaking and only ever ship behind a new Gauge-Version date or a new path:

• removing or renaming a field, an endpoint or an error.code;
• changing a field's type or meaning;
• making an optional request field required.

DeprecationCopy Anchor Link

Before an endpoint is retired, its responses carry the standard headers:

Deprecation: @1798761600
Sunset: Sun, 01 Aug 2027 00:00:00 GMT
Link: <https://docs.gauge.chat/changelog>; rel="deprecation"

Nothing is deprecated today. Every deprecation is also announced in the changelog.