# Versioning and changelog

Distinguish the route, document, definition and item versions.

Source: [Versioning and changelog](/versioning/)

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.1`                                                                 |
| `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. Select a renderer using both the key and version. If a response contains a variant your application does not support, retain the snapshot and skip that item's rendering rather than treating its content as another version. Schema availability does not imply that every feed publishes that variant.

## Current contract changes [#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; captured public examples from [fixture 0012600066](https://api.live.storyos.ai/v1/fixtures/0012600066/feeds/pulse) are in [Item types](/markdown/item-types.md). |
| Run Momentum version 1                                | An additional NBA content definition, also demonstrated by that public fixture.                                                                                                             |

## Documentation changelog [#documentation-changelog]

The reference is built from the same bundled contracts served by the API. OpenAPI document version 0.2.1 includes all thirteen NBA definition/version variants and the sample/live caching and replay behavior. It changes no feed route or definition version. Copy length guidance is a writing target; the content schemas do not impose headline or summary length limits.