Versioning

Streamboards are append-only at the spec level. Every call to the MCP update_streamboard tool inserts a brand-new row with version = max(version) + 1 — the previous version is never overwritten. State (the values pushed by your code) is not versioned and is shared across all spec versions.

Inspecting history

• MCP: list_versions(id) returns every version with the version number, creator, and timestamp.
• CLI: streamboard streamboards versions <id>
• Viewer: settings gear → Version history

Pinning to a version

A streamboard URL with no version segment (/s/<id>) always renders the latest spec. To pin to an earlier version, use /s/<id>/<version>:

https://usestreamboard.com/s/26082684/3

Pinned URLs are immutable + cache-friendly (max-age=31536000, immutable). The latest URL has a short cache (s-maxage=60, must-revalidate).

State across versions

State is stored in a single streamboardState row per streamboard, keyed by streamboardId (not by (id, version)). A pinned older version renders against the current state envelope — meaning if you rename a bind path from kpis.mrr to metrics.mrr, an older version’s $bind: "kpis.mrr.value" ref will resolve to undefined once the new pushes use metrics.mrr.value.

In practice: avoid renaming bind paths. Add new paths if you need new fields; keep old ones around for a deprecation window.

Rolling back

There’s no in-place rollback. To “restore” v3 after a bad v7:

1. get_streamboard(id, version: 3) to fetch the older spec
2. update_streamboard(id, spec: <that spec>) to mint v8 = a copy of v3

Both v7 (the bad one) and v8 (the restored copy) survive in history.

Concurrent updates

update_streamboard uses a single atomic INSERT … SELECT version + 1 FROM streamboard WHERE id = ? SQL statement, so two workers calling it simultaneously will produce sequential versions (v8, v9) without colliding on the (id, version) primary key.