Versioning

The API is versioned by its path prefix. Everything you build against /v1 stays compatible for the life of v1, because a breaking change is not allowed inside a major version. It would require a new one.

The contract

Version lives in the path. Every public operation sits under the /v1/ prefix. That prefix is the version you are pinned to.
A breaking change means a new major. Anything that could break an existing client, removing a field, renaming one, changing a type, tightening validation, cannot land within /v1. It would appear under a new major prefix, side by side with the old one.
Additive changes are safe and in place. New endpoints, new optional request fields, and new response fields can land within /v1 without a version bump, because they do not break a client written against the older shape.

What is and is not breaking

Change	Breaking?	How it ships
New endpoint added	No	In place, under `/v1`.
New optional request field	No	In place, under `/v1`.
New field in a response body	No	In place. Tolerate unknown fields in your client.
Field removed or renamed	Yes	Only in a new major.
Field type or format changed	Yes	Only in a new major.
Validation tightened on existing input	Yes	Only in a new major.

Write your client to ignore response fields it does not recognize. New fields arriving in /v1 are expected, and a tolerant parser means additive releases never need code changes from you.

The shape is locked

The public request and response shapes for /v1 are fixed. Public identifier formats, response field names, status codes, and header contracts do not drift inside the major version. This is what makes it safe to generate clients and types against the contract and keep them. When a surface genuinely must change in a breaking way, it is deprecated first with notice, not altered in place. See Deprecations.

Related dimensions

After its first public release, the SDK will carry its own semantic version and can advance independently of the /v1 API namespace. The underlying smart contract layer is versioned separately too, and deployed addresses can change across major versions. For your integration, the /v1 path prefix is the version that matters.

The initial npm semantic version and authoritative license text are release inputs. XKOVA does not infer either value from workspace package metadata, OpenAPI metadata, a build date, or a source revision. An npm artifact is not a release candidate until both inputs are approved and the exact tarball passes publication certification.

See the Changelog for what shipped in each release, and Deprecations for how a surface is retired before any breaking removal.

Was this helpful?