Versioning Policy

The Cheetah hardware platform and operator applications are stable and shipping. This page is not about them.

The Cheetah developer integration surface — HTTP API, Python and TypeScript SDKs, webhook event payloads — is in early alpha. These may change between releases without prior notice. If you're building a production integration today, pin to specific versions and plan for breaking changes.

This page tells you what we version, how to know which version a docs page applies to, what guarantees we make today, and what changes when we cut a stable v1 of the integration surface.

What we version

Cheetah ships on three independent version axes.

Axis	Surfaces it covers	Versioning source
cheetah-service	HTTP API, Python SDK (cheetah-client), TypeScript SDK (@cheetahengineering/cheetah-client)	One version per release — OpenAPI info.version, the Python package version, and the TypeScript package version all move together. Current: v0.0.129.
cheetah-ui applications	Each route-app under cheetah-ui (operator, program-builder, system-config, cheetah-validation, aux-file-manager, ljs-navigator)	Per-app version tag, e.g. program-builder/v0.1.x. Apps version independently of each other and of cheetah-service.
Webhook event payloads	Push-delivered events	Per-event schema_version field. Current schema generation: 2.

Two implications worth being explicit about:

• API and SDKs move as one. The Python and TypeScript SDKs are released alongside the HTTP API in cheetah-service. There is no independent SDK version — the package version is the service version. If you see cheetah-client==0.0.129, that SDK was built against API 0.0.129.
• Webhook schemas are decoupled. Bumping the API version does not bump schema_version, and bumping schema_version does not bump the API version. Each event payload tells you its own version.

SDK installation

Python — cheetah-client

During alpha, install from the source repository pinned to a specific tag:

pip install "cheetah-client @ git+https://github.com/CheetahEngineering/cheetah-service.git@v0.0.129#subdirectory=clients/python"

Or with uv:

uv add "cheetah-client @ git+https://github.com/CheetahEngineering/cheetah-service.git@v0.0.129#subdirectory=clients/python"

Pin to a specific tag (e.g. @v0.0.129) rather than @main — main will move under you.

TypeScript — @cheetahengineering/cheetah-client

Published to the GitHub Packages registry, not public npm. You need a GitHub token with read:packages scope.

In your .npmrc:

@cheetahengineering:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

In your package.json:

"@cheetahengineering/cheetah-client": "0.0.129"

Install:

GITHUB_TOKEN=$(gh auth token) pnpm install

The ${GITHUB_TOKEN} env var must be set at install time; pnpm will 404 on the dependency otherwise.

How to know which version a docs page applies to

Every page that depends on a specific surface version carries an applies_to banner at the top:

Applies to: cheetah-service ≥ 0.0.129. Webhook events: schema_version ≥ 2.

The banner declares the minimum version each surface must be on for the documented behavior to be accurate. If you're on an earlier version, expect divergence.

Every page also includes a build-time stamp in the footer — e.g., "Last verified against cheetah-service 0.0.129 (built 2026-05-24)." This is generated automatically when the docs are built and reflects the version the examples were tested against.

The API reference surfaces the OpenAPI info.version prominently — it's authoritative. If the reference page and a narrative docs page disagree about a field, trust the reference.

What we guarantee during integration-surface alpha

While the integration surface is in alpha, our versioning posture is:

• No semver guarantees. A patch bump (v0.0.128 → v0.0.129) may include breaking changes. Plan for that.
• No formal deprecation window. Endpoints, fields, and event shapes may be removed in any release.
• Changelogs are the source of truth. Every release is documented in cheetah-service/CHANGELOG.md with breaking changes flagged using the conventional-commit feat!: or fix!: syntax. UI apps are documented in cheetah-ui/CHANGELOG.md.
• Pin everything. Pin your SDK version, the OpenAPI spec version you generated against, and the cheetah-ui application version your team trains against.

This posture is intentional and scoped. The hardware platform and operator applications are not alpha — they're shipping to customers. The integration surface is iterating fast because we'd rather change the wrong shapes now than commit to them too early. We'll reach v1 of the integration surface with shapes worth committing to.

Webhook event payload versioning

Webhook event payloads are versioned independently of the HTTP API. Every event delivered carries a schema_version field. All events currently ship at schema_version: 2.

When we change a payload shape:

• The new shape ships under a higher schema_version.
• Existing subscribers continue to receive the previous shape during a transition window. The length depends on the change and is announced in the changelog.
• New subscribers default to the latest shape.

This decoupling lets us evolve event schemas without forcing every consumer to update simultaneously. Payload schemas per event are documented in the event reference.

What changes when we cut v1

When Cheetah reaches a stable v1, the following commitments take effect:

• Semantic versioning for the HTTP API. Breaking changes only on major version bumps.
• URL-versioned API and docs. Both move to versioned paths (/v1/...). Alpha-era docs remain accessible at their original URLs as frozen references.
• Minimum 90-day deprecation notice for any endpoint, field, or event payload removal, surfaced in the changelog and on each affected docs page.
• Sunset and Deprecation HTTP headers on responses from endpoints scheduled for removal, per RFC 8594.

We are not at v1 yet. Do not depend on these commitments until we explicitly announce the cut.

When documented behavior doesn't match reality

If something the docs describe doesn't match what you're seeing:

1. Check your SDK and API versions against the page's applies_to banner.
2. Check the changelog for recent breaking changes in the surfaces you depend on.
3. If versions match but behavior diverges, that's a docs bug — please report it via support.

During alpha, when narrative docs and machine-generated sources disagree, the OpenAPI spec and the SDK source are more authoritative than prose. We work hard to keep them aligned, but iteration sometimes outpaces the docs.