Versioning

API versioning

The KATforge API is versioned in the URL path:

text

https://api.katforge.com/v1/...

There is currently one version: v1. All endpoints in this documentation live under /v1.

When (if) we ship a breaking change, it will land under a new prefix (/v2) and the old version will continue to work for at least 12 months. We aim never to break v1 in place.

What counts as a breaking change

Change	Breaking?
Removing an endpoint	✅ Yes
Removing a request field	✅ Yes
Removing a response field	✅ Yes
Renaming a field	✅ Yes
Changing a field's type	✅ Yes
Tightening validation rules	✅ Yes
Adding a new endpoint	❌ No
Adding an optional request field	❌ No
Adding a new response field	❌ No
Adding a new enum value	⚠️ Treat as breaking — add a fallback in your client
Loosening validation rules	❌ No
Improving error messages	❌ No

Deprecated endpoints are marked with @deprecated in their docblock and shown with a strikethrough in the API Reference. They continue to work for at least 6 months after deprecation. Migration paths are documented in the deprecation notice.

The most notable currently-deprecated endpoint is GET /v1/tokens/validate — clients should validate JWTs locally (the SDK does this automatically).

SDK versioning

The @katforge/api SDK uses semver:

Version bump	Meaning
Patch (`0.1.x`)	Bug fixes, internal refactors. Always safe to upgrade.
Minor (`0.x.0`)	New methods, new features. Never breaks existing code.
Major (`x.0.0`)	Breaking change. Pinned in your `package.json`.

The SDK is currently 0.x — minor versions can include breaking changes. We'll cut 1.0 once the API is stable in production for a quarter.

Tracking changes

CHANGELOG — released alongside every SDK version on GitHub.
OpenAPI diffs — the spec at /v1/openapi.json is regenerated on every API deploy. You can git diff two snapshots to see exactly what changed.
@deprecated warnings — appear in your IDE if you use the SDK with TypeScript.

Pinning

In production, always pin the SDK to a known-good minor version:

JSON

{
   "dependencies": {
      "@katforge/api": "~0.1.0"
   }
}