API versioning and deprecation
What stays stable within a major version, what counts as breaking, and how much notice you get before anything is removed. Releases are listed on the changelog.
What carries a version
The runtime API is versioned in the path: /v1/query, /v1/bootstrap, /v1/artifact and /v1/selection. The control-plane API lives under /api/v1/, for example /api/v1/token, and the browser build of the SDK is served from /sdk/v1/autosugges.js. All of them are major version 1, and there is no version 2.
A published list version is a different thing. Publishing a list creates a new immutable list version with its own hash; it never changes the API version, and a new API version never republishes your lists. The two are independent.
The session-authenticated dashboard routes under /api/ without a version segment are what the AutoSugges dashboard itself calls. They are not part of the versioned contract today.
What can change within v1
Within a major version, changes are additive. A response may gain a new field, a request may accept a new optional parameter, and a new endpoint may appear. Ignore fields you do not recognise rather than rejecting the response.
A new error code may be added. Switch on the codes you handle and treat any other code as a generic failure using its HTTP status and retryable flag.
What counts as breaking
A change is breaking if a client written correctly against the current documentation could stop working: removing or renaming a response field, changing a field type or meaning, making an optional parameter required, removing an endpoint, or changing the status or error code returned for an existing condition.
A breaking change to a response ships only under a new major version, such as /v2/query, served next to /v1 rather than in place of it.
Deprecation and notice
A deprecated endpoint, field or SDK major keeps working for at least 180 days after the deprecation is announced on the changelog. That period is provisional and may lengthen; it will not shorten for anything already announced.
Every deprecation publishes migration guidance with it: what replaces the old behaviour, the exact change a client makes, and a Copy for AI / LLM block with self-contained migration instructions.
No v1 endpoint or field is deprecated today.
Staying current
Read the changelog for every release. Pin the major version in the paths you call, and never build a URL from a version string you discovered at runtime.