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.

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	What it tells you	Changes when
Documentation version	The documentation release a page belongs to. Format YYYY.MM.	A batch of documentation changes is published.
Page review date	The last time the page was checked against the product.	Someone verifies that the page still matches reality.
API version	On API pages, the API version the page was verified against. See API versioning.	The page is confirmed against a new API version.
Product version	What Insights delivers. See the Release notes.	Insights itself ships.

Reading the stamp

Every page ends with a line like this one:

DOCS 2026.10     REVIEWED 2026-10-01     API 1.7

• 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 documentation release 2026.08.
• API — on API pages, the API version the page was verified against.
• Documentation changelog — the link that leads to this page, at the end of the line.

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.

Releases

2026.10

Calculated variables

Calculated variables described the engine as evaluating calculations point by point, with each window stopping at the received point. Neither is true. The page now describes how the engine actually triggers a calculation and positions its windows.

• New: How a calculation is triggered — one calculation per stored batch of points, not per point; batches of the same variable stored within about a minute of each other are merged, whatever the gap between their timestamps.
• New: definitions of the datapoint date (the earliest point of the batch) and the trigger date (the moment of calculation), and the window they produce: from the datapoint date minus the past Period, up to the trigger date plus the future Period.
• New: a catch-up example. A past window always runs up to the moment of calculation, so re-injecting old data reads every input from that date up to now.
• Fixed: the time reference rules spoke of a "future-dated calculated variable"; they concern the point that triggers the calculation.
• Fixed: with a master input expressed as a number of points, the slave input is read between the first and the last point retrieved for the master, not from its start only. A slave can itself be a trigger.
• Fixed: N previous points also retrieves every point between the datapoint date and the trigger date.
• Fixed: the 2-year bound on future windows is the forecast horizon of the account, configurable per account.
• Fixed: three diagrams of the best-practices section had overlapping or clipped labels.

API documentation

Python client reviewed against version 1.7 of datahub-api-connector.

• New: Lifetime of an instance — an instance holds open connections and must be reused and closed; one per account, never closed, eventually runs the machine out of sockets.
• New: network failures are retried on every method, writes included; the unsafe-method setting only governs HTTP statuses.
• New: datetime parameters are sent without time zone, and date_from is sent as from.
• New: the former OPINUM_* environment variables are still read.
• Fixed: the storage upload is neither retried nor raised on an HTTP error; the page said nothing of it.
• Fixed: a Retry-After header is capped at 60 seconds like the computed wait.

Technical documentation

• Removed: the Open Data Model GraphQL section — sixteen pages with their samples and diagrams. The service has been decommissioned. Open Data Model over SQL remains the way to model your own domain.

2026.08

Three sections were reviewed end to end. The scheme described on this page was introduced with this release.

API documentation

Reviewed against the V1.7 Swagger definition, a real integration, and a live read of the metadata endpoints.

• 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, with the small enumerations read live from the API on 2026-08-28, and the unit conversion model (reference = (value − offset) × divisor) documented and verified.
• New: Recipes — task-oriented examples.
• New: .NET client and Python client.
• Fixed: the "API introduction" entry of the table of contents 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.

Technical documentation

An audit of the 93 pages of the section, followed by a content review.

• New: Technical documentation — the landing page was a single sentence for a 93-page section. It is now a map of the five families.
• New: Geozones — the page existed but was empty. Written from the V1.7 Swagger; geozones were also absent from the table of contents.
• New: Webhooks or data forwarding? — the two mechanisms overlap and nothing said which to use. The retry policy is now diagrammed, with the point that a failing hook goes silent after roughly half an hour and nothing re-enables it.
• Fixed: 21 dead links on the published site, two of which displayed as raw text instead of a link.
• Fixed: 4 pages had no title, 9 had several main headings, 4 could not be reached from the navigation or from any link, and one page was published empty.
• Reviewed: Master Data — the two-file model, the nine processing phases and the business key are now each explained with a diagram. The JSON template page announced five root properties and listed six, one of which the sample does not use while omitting one it does.

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.

Corrections to this release

• Querying the API claimed the CustomFilter grammar was unspecified. It is documented — Custom filter query syntax carries the operators, the type rules and a BNF grammar. The page now links to it.
• Python client stated that no Verity-maintained Python package existed. The datahub-api-connector package supersedes the retired opinum-api-connector, and the page now documents it — version 1.6, its retry model and its parallel-call helper — instead of a hand-rolled client.

Before 2026.08

Changes predating this release are not listed.

DOCS 2026.10 REVIEWED 2026-08-28 Documentation changelog →