Versioning and deprecation

How the API is versioned

The version is in the path. Every endpoint lives under /v1/, and no header or query parameter selects a version. A new major version gets a new path (/v2/) next to the old one, never in its place.

Changes within v1

Within /v1/ the API only grows. At any time it may add:

new endpoints and new engines;
new optional request fields and new include flags;
new fields in a response, including inside nested objects;
new error codes and new values of fields documented as open-ended.

These ship without notice and are listed in the changelog. Prices and the countries an engine answers from are service terms, not part of the schema: they are published on pricing and in coverage, and their changes are dated in the changelog too.

What counts as breaking

A change is breaking when a working client could fail or misread a response. These go to a new version:

removing or renaming an endpoint, a request field or a response field;
making an optional request field required, or narrowing the values it accepts;
changing a field's type or the meaning of its values;
changing the error envelope or the meaning of an existing error code.

A field that exists but comes back empty stays in the schema with its type. For example, ChatGPT's searchQueries is an empty list on the answers served today, and the engine pages say so.

Deprecation and notice

A deprecated endpoint says so in every response. Deprecation (RFC 9745) carries the date it was deprecated, Sunset (RFC 8594) the date it stops answering, and a Link header with rel="deprecation" points to the replacement. For generally available endpoints the two dates are at least six months apart, and the changelog records the deprecation on the day it starts. No endpoint is deprecated today.

Writing a client that lasts

Ignore response fields you don't know, and treat optional fields and lists as possibly absent or empty.
Branch on error.code, never on error.message. See errors.
Log the Deprecation and Sunset headers when they appear, so a planned removal reaches you.
Pin an SDK version and read the changelog before you upgrade it.