Versioning and changelog
Distinguish the route, document, definition and item versions.
These four values describe different things:
| Version | Purpose | Current examples |
|---|---|---|
| Route version | The HTTP contract in the path. | /v1 |
| OpenAPI document version | Version of the published integration reference. | 0.2.0 |
definitionVersion | Version of one definition’s content shape. | Player Performance 1 or 2; not an API route version. |
revision | Publication revision of one item identity. | Starts at 1; rewritten content keeps its ID and increases revision. |
The current schemas are strict. A breaking generic envelope change calls for a new API contract version; a breaking definition-specific content change calls for a new definitionVersion. There is no top-level schemaVersion field. Support definitions explicitly by key and version and contact Storyteller before assuming a newly defined variant is enabled for your feed.
Current contract changes
This is a capability record, not a claim about when a live feed enabled each definition.
| Change | Available reference |
|---|---|
| Public fixture index and replay bounds | The twelve generated samples support atAction and asOf; Portland remains an unfiltered version 1 example. |
| Public live reads | Live NBA feeds on the existing fixture/feed route, with no key (per-client keys were removed on 6 October 2026). |
| Player Performance version 2 | headline, statLine and integer actionNumber, plus a wider set of statistic scopes; demonstrated in the public samples. |
| Team Performance version 2 and Four Factors version 2 | Defined in the NBA schema; no public fixture examples for these versions. |
| Run Momentum version 1 | An additional NBA content definition in the schema; no public fixture example. |
Documentation changelog
This documentation edition introduces the client guides and renders the reference from the same bundled contract served by the API. It changes no feed routes, schemas or item behavior. No complete historical release chronology is published here; contact Storyteller for integration change notices.