Versioning and deprecation

What is covered

The stability promise covers the public operations — exactly the ones documented in this reference. Anything else a client might discover is not part of the contract and can change without notice.

What "stable" means

• Nothing you rely on is removed or renamed without a version change. Parameters, response fields and error codes are added to, never taken away or reshaped.
• Unknown fields are safe to ignore. Optional fields are added to responses over time. A client that ignores JSON fields it does not recognise keeps working across additive updates with no change.
• Error codes are a closed, append-only set. New codes arrive only for new failure modes; existing ones are never repurposed or removed. Branch on code, not message.

Protobuf exception. If you decode a protobuf body and re-encode it with an older copy of the schema, fields that copy does not know are dropped. Treat decoded messages as read-only, or keep your schema current.

What counts as breaking

• Removing or renaming a public operation, path, parameter or response field
• Narrowing a field's type, or removing an enum value you might match on
• Adding a new required parameter
• Removing an error code

None of that ships inside /v2. It ships as a new major surface (/v3), or — rarely, when a fix cannot wait — as an announced exception, named in the changelog.

Adding an operation, an optional parameter, an optional response field or a new error code is not breaking and can land in a routine /v2 update.

How you will be told

• The contract version moves. The API document carries info.version (today: 0.8.1). Compare it across time to see whether anything changed.
• The changelog lists public changes: changelog.
• Deprecation headers. Anything scheduled for removal carries Deprecation and Sunset response headers (RFC 8594), plus a Link to its replacement. Sunset is the date it stops working.
• Minimum notice: 90 days from the first response carrying Sunset to the date in it.

Check those headers in code, on your real traffic — do not rely on reading the changelog by hand.

How to pin

• Test against a specific contract version and re-check the changelog before upgrading.
• Upgrade the SDKs on a version bump rather than assuming an old client picks up new optional fields.
• When /v3 arrives, /v2 keeps running through the deprecation window; there is no forced same-day cutover.