Versioning & Deprecations
The rules the surface evolves by, and the live list of everything currently deprecated, frozen, or defined-but-not-yet-emitted.
Versioning rules
- REST: versioned by URL prefix (
/api/v1). Breaking changes to a shipped route mean a new route or namespace, never a silent in-place change. The contract is exactly the generated OpenAPI artifacts. - Webhook events: progression events carry
.v1; a payload-breaking change ships as.v2alongside.v1during the deprecation window. Legacy activity events (activity.completed, ...) are unversioned and FROZEN: no shape changes, ever. - Errors: the envelope carries version 1. New codes may be ADDED at any time (tolerate unknown codes); existing codes and types are never renamed or repurposed.
- SDKs: semver. Removing or reshaping an export is a major bump.
- Process (pre-GA): every removal is recorded in the changelog with its replacement. Post-GA this hardens to a 90-day announced window with
Deprecation/Sunsetheaders.
Currently deprecated or deferred
| Item | Status | What to do |
|---|---|---|
GET /gamify/participants/{id} (full profile) | Deprecated in favor of the canonical state read | Use GET /gamify/state/{id}?include=... |
reward.expired.v1, game.completed (webhook events) | Deferred: subscribable, schema-published, no emitter yet (catalog status deferred) | Do not block an integration waiting on them |
engagement:completed client message / onComplete prop | Declared but not emitted by the runtime | Derive completion from activity:completed; see Client Events |
| Legacy activity webhook events (unversioned) | Frozen (no shape changes; no .v1 rename planned) | Safe to consume as-is |
Legacy hook useEngagement | Deprecated; removal scheduled in a future SDK major | Use useEngagementData |
Removed 2026-07: legacy /points/*, /rewards/claimed, /ingest/events* routes | Gone (404) | Replacements listed in the changelog |