API Versioning Policy

The KINGSTONE Partner API uses path-based versioning to give partners a stable, predictable integration surface. This page explains how versioning works, what guarantees you get, and how to stay informed about changes.

Current Version

Property	Value
API version	v1
Base URL	/api/partner/v1/
Semver	1.0.0
Status	Stable — production ready

Check your version programmatically:

curl https://api.kingstone.dev/api/partner/v1/version

Response:

{
  "version": "1.0.0",
  "apiVersion": "v1",
  "service": "KINGSTONE by Predigy Inc."
}

How Versioning Works

The API version is embedded in the URL path:

/api/partner/v1/spin
/api/partner/v1/games
/api/partner/v1/par-sheets

When a new major version is released, it will be available at a new path:

/api/partner/v2/spin

The previous version continues to work during the deprecation window (see below).

Backward Compatibility Guarantee

Within any version (e.g., v1), we guarantee backward compatibility for all existing integrations. We will never ship a change to v1 that breaks a working client.

What is NOT a breaking change

These changes may happen at any time within v1 and will not require you to update your integration:

• Adding new fields to JSON response bodies
• Adding new endpoints (e.g., GET /partner/v1/reports)
• Adding new optional query parameters to existing endpoints
• Adding new error codes (e.g., KS-2050)
• Adding new enum values where documented as extensible
• Relaxing validation (accepting values that were previously rejected)
• Improving error messages (human-readable text may change)

Best practice: Your client code should ignore unknown fields in responses. The KINGSTONE SDK handles this automatically.

What IS a breaking change

These changes will never happen within an existing version. They require a new major version (e.g., v2):

• Removing a field from a response body
• Changing a field's type (e.g., string to number)
• Renaming a field in a request or response
• Removing an endpoint
• Changing authentication requirements (e.g., new required header)
• Changing the meaning of an existing error code
• Tightening validation in a way that rejects previously-accepted requests
• Changing HTTP methods for existing endpoints

Deprecation Policy

When a new major version is released:

1. Announcement — Partners are notified via webhook (api.version.deprecated event) and email at least 6 months before the old version is retired.
2. Deprecation period — The old version continues to work for 6 months after the new version launches. Both versions run side-by-side.
3. Sunset headers — Deprecated endpoints include a Sunset HTTP header with the retirement date and a Deprecation header with the deprecation date.
4. Retirement — After the 6-month window, the old version returns 410 Gone with a message directing partners to the new version.

Timeline Example

Date	Event
2027-01-01	v2 released, v1 marked deprecated
2027-01-01	Sunset: Tue, 01 Jul 2027 00:00:00 GMT header added to v1 responses
2027-07-01	v1 retired — returns 410 Gone

Checking Your Version

Use the version endpoint to confirm which version you are connected to:

GET /api/partner/v1/version

The KINGSTONE SDK exposes this as:

const info = await client.getVersion();
console.log(info.apiVersion); // "v1"
console.log(info.version);    // "1.0.0"

The KINGSTONE CLI can also check:

kingstone version

Changelog

All changes to the Partner API are documented in the CHANGELOG.md file in the API package root. Each release includes:

• New endpoints and features
• Bug fixes
• Deprecation notices
• Migration guides (for major versions)

Questions?

If you have questions about versioning or need help migrating between versions, contact your partner integration manager or reach out via the support channels in your partner dashboard.