Skip to main content

Versioning

The Xavigate API uses major version in the URL path plus dated minor versions via header.

Path version​

The path prefix (/v1/) identifies the major API version. Breaking changes require a new major version (/v2/).

The current version is /v1/.

Dated versions​

Non-breaking changes (new fields, new endpoints, new event types) are released with a date stamp. Your account pins to the API version at the time of your first request.

To use a specific dated version, pass the Xavigate-Version header:

Xavigate-Version: 2026-04-21

If the header is absent, your account-pinned version is used.

Version pinning​

When you first make a request, your account is pinned to the current API version. This means new fields and changes introduced after your pinning date won't appear in your responses unless you explicitly update your pinned version.

To update your version pin:

  1. Review the changelog for changes since your current pin
  2. Update your code to handle any new/changed fields
  3. Update your pinned version in dashboard → Account → API Version

Deprecation policy​

Breaking changes require 12 months notice (per ADR-010). During the notice period:

  • The old behavior continues to work
  • Deprecation warnings appear in response headers (Deprecation: true, Sunset: <date>)
  • The changelog documents the change with migration instructions

After the deprecation window, the old behavior is removed.

Beta exception

The 12-month deprecation policy does not apply during the closed beta period. Breaking changes may occur without notice. The policy activates at v1 GA (public beta, frozen contract).

Changelog​

See the Changelog for a full history of API changes.