Versioning & stability
This page explains what you can rely on as you build, and what may still change.
API versioning
The API is versioned in the path — every endpoint lives under /v1/. We add fields and endpoints
without bumping the version; breaking changes ship as a new version.
For /v1, additive changes include new endpoints, new optional request fields, new response fields,
new error metadata fields, and new SDK helpers around existing endpoints. Breaking changes include
removing or renaming fields, changing required fields, changing enum meanings, changing auth
semantics, changing credit-charging behavior, or changing an endpoint path/method.
The formal support window for a GA version is not set during closed beta. Until GA, treat the published OpenAPI file and changelog as the compatibility source of truth.
What "closed-beta preview" means
The current contract is a closed-beta preview. It's stable enough for invited developers to build against, but some shapes may still change before general availability.
The published preview contract is pokerworks-alpha-preview.openapi.json. The calculation endpoints,
credential prefixes (pw_test_, pw_live_, pw_mgmt_), and calculation response envelope are the
parts we are hardening toward GA. The management API, private CLI/MCP tooling, billing semantics,
and SDK distribution remain beta surfaces and can change before public GA.
We avoid silent breaking changes. If a preview shape needs to change, the docs and changelog should move with the runtime change, and generated reference output should be updated from the current OpenAPI/runtime schemas.
Deprecation policy
Deprecations are announced in the changelog and on the affected docs pages. A formal email/header-based deprecation program and notice window are not yet part of the preview contract; they will be defined before any GA deprecation/removal policy is promised.
SDK versioning
The SDKs follow semantic versioning and track the API contract. Pin a version in production and review the changelog before upgrading.
The public calculation SDK is planned as @pokerworks/sdk; the public management client is planned
as @pokerworks/management. Current similarly named workspace packages are private monorepo
packages and are not beta install paths. Public npm distribution, major-version support windows,
and SDK-to-API-version support promises come with the SDK release plan.