Documentation changelog

This documentation carries a version of its own, independent from the version of Insights and from the version of the API. Every page displays it in the stamp at the bottom, next to the date the page was last reviewed.

How the three version numbers relate

Why three different numbers

Golden rule

The product version says what exists, the API version says what a call returns, the documentation version says what has been written down.

They move at different speeds and cannot be merged into one. A page can be rewritten without any product change, and a product release can ship before its documentation catches up — the stamp is what makes that visible instead of leaving the reader guessing.

Number Where it lives Changes when
Documentation version _docVersion in docfx.json, shown on every page A batch of documentation changes is published. Format YYYY.MM.
Page review date lastReviewed in the page's front matter Someone verifies that a given page still matches reality.
API version apiVersion in the front matter of API pages The page is confirmed against a new API version. See API versioning.
Product version Release notes Insights itself ships.

Reading the stamp

Every page ends with a line like this one:

DOCS 2026.08     REVIEWED 2026-08-28     API 1.7        Documentation changelog →
  • DOCS — the documentation release this page belongs to.
  • REVIEWED — the last time a human confirmed the page against the product. Absent means never formally reviewed since the convention was introduced.
  • API — on API pages, the API version the page was verified against.
Tip

A page whose REVIEWED date is far behind the current DOCS version is not necessarily wrong, but it is the first place to look when the documentation and the product disagree.

Marking a page as reviewed

Add the keys to the YAML front matter of the page. Both are optional and independent:

---
uid: my-page
lastReviewed: 2026-08-28
apiVersion: "1.7"
---

Use the ISO date format, YYYY-MM-DD. apiVersion only makes sense on pages that describe the API; leave it out everywhere else.

Note

The stamp can be suppressed on a page — a landing page, for instance — with _disableDocVersion: true in the front matter.

Publishing a documentation release

  1. Bump _docVersion and _docVersionDate in docfx.json.
  2. Add an entry to the Releases section below, describing what changed and why.
  3. Update lastReviewed on the pages that were actually verified — not on the ones that were merely touched.

Golden rule

Bump lastReviewed only when you have checked the page against the product.

A review date that gets refreshed by a typo fix stops carrying information. If nobody verified the content, the honest date is the old one.

Releases

2026.08

API documentation — the section was reviewed end to end against the V1.7 Swagger definition and a real integration.

  • New: Getting started, an end-to-end walkthrough from token to first data point.
  • New: Querying the API — entity chain, shared filtering conventions, full GET /data reference, aggregation semantics.
  • New: Files and triggers — the /storage and /fileTrigger endpoints.
  • New: Reference data — the identifier referentials exposed by the metadata endpoints, with the small enumerations listed from a live read of the API on 2026-08-28, and the unit conversion model (unitFamilyId, parentId, divisor, offset) documented and verified.
  • New: Recipes — task-oriented examples.
  • New: .NET client and Python client.
  • Fixed: the "API introduction" TOC entry pointed at the User Manual home page.
  • Fixed: the 1.7 row of the API version table was truncated.
  • Fixed: the connection page listed 2 of the 5 OAuth2 scopes.
  • Removed: the page describing the deprecated opinum-api-connector Python package.
  • Introduced: this versioning scheme and the per-page stamp.

Calculated variables — the R contract is now documented: what the engine passes to the script, what the script must return, and the anatomy of a formula.

Before 2026.08

Changes predating this scheme are not listed. Use the repository history.

DOCS 2026.08 REVIEWED 2026-08-28 Documentation changelog →