Versioning and deprecation policy

This page documents how AACSearch versions every public surface and the shelf-life of a deprecated feature.

API versioning

The REST API is versioned in the URL: /api/v1/.... New versions appear when:

• A response shape changes in a backwards-incompatible way.
• A required field is added or removed.
• An auth requirement changes (e.g. scope-token enforcement broadens).

Additive changes (new optional fields, new endpoints, new optional parameters) do not trigger a new major version. They land in the current version with a Changed/Added changelog entry.

The current major versions in production:

We avoid spinning a new major unless an additive solution is genuinely impossible. New majors carry a 12-month overlap with the previous major.

SDK versioning

Every SDK package follows Semver:

• MAJOR — breaking change to the API of the SDK itself or to the underlying REST surface it targets.
• MINOR — new methods, new optional arguments, new types.
• PATCH — bug fixes, internal cleanup, dependency bumps without API surface change.

SDK packages tracked here:

• @aacsearch/client — TypeScript browser + server SDK.
• @aacsearch/react — React hooks (useAACsearch, useAACSuggest, useAACFacet).
• @aacsearch/widget — Vanilla JS Shadow DOM widget.
• aacsearch (Python) — Python client.

Release notes live in /changelog/sdk. Each release has a git tag matching the npm/pip version and a release entry in this docs page.

Widget versioning

The widget is a UMD/ES bundle loaded as a <script> tag. Versions are pinned by URL:

<script src="https://cdn.aacsearch.com/widget/v1/widget.js"></script>

The latest channel stays at the latest stable major. Pinning to a major (v1, v2) is allowed and recommended for production. Pinning to an exact patch is allowed but not recommended — patches ship security fixes.

Breaking changes always wait for a new major URL. The previous major stays available on the CDN for 12 months after the new major ships.

Connector protocol versioning

Connector protocol versions are a separate stream. The platform.minModuleVersion returned from /api/connectors/handshake declares the minimum version a connector module on the customer side must meet. When that floor moves, the change ships in /changelog/connectors with a 60-day notice for existing connector modules.

Deprecation timelines

Every deprecation must:

1. Land in the Deprecated bucket of the relevant changelog page.
2. Carry a removal date in the entry.
3. Have a migration page under /migration/<from-version> if the migration takes more than a few lines.
4. Trigger a X-Deprecated response header on the API surface for the notice period.

Docs versioning

Docs are not versioned per release — the live /docs site reflects the current production state. When an API major flips:

• The previous major's docs move to /docs/v<n>/....
• The new major's docs replace /docs/....
• The /migration/v<n>-to-v<n+1> page documents what changed.

Historical docs for vN stay available read-only until the deprecation window for vN closes.

Linking from the changelog

Every changelog entry that introduces a versioned surface change should link here. The format is:

### Changed

- **API**: Search response now includes `tookMs` field. Additive — no
  version bump required. See [Versioning](/changelog/versioning) for the
  versioning rule.

Out of scope

• Pre-release tags (alpha, beta, rc) follow npm semver pre-release rules; documenting their precise meaning per package is the SDK release notes' job.
• Internal infra version bumps (Postgres, Typesense, etc.) are not user-facing and are not listed in this changelog.