API documentation
The Verity Insights API is a REST/JSON API that exposes everything the web interface does: the structure of your account, the measurement data it holds, and the monitoring and reporting built on top of it.
Three hosts, one token
Integrations touch three different hosts. They are separate services with separate roles, but a single token opens all of them.
| Host | Role | Documented in |
|---|---|---|
auth.opinum.com |
Issues the OAuth2 bearer token. | Connect to the API |
api.opinum.com |
The main API: read and write sites, sources, variables, data, alarms, reports. | Querying the API |
push.opinum.com |
Ingestion of data points at volume, in the standard or in a custom format. | Standard format, Custom format |
Tip
If you are sending measurement data, use push.opinum.com. If you are creating structure, correcting data
or reading anything back, use api.opinum.com. The two are not interchangeable —
Choosing a route walks through the
decision.
What the API covers
Version 1.7 exposes 292 paths and 411 operations, grouped into a handful of functional families.
The complete, always-current reference is the Swagger definition itself — this documentation covers the conventions that the Swagger cannot express: how the resources relate to each other, how filters combine, and which patterns hold up in production.
Swagger UI — browse and call every endpoint with your own token.
swagger.json — the OpenAPI 3.0 definition, for client generation.
support@opinum.com — credentials, dedicated GUIDs, and anything the docs do not answer.
Versioning
A new version is published only when a breaking change is introduced. Adding a new property or a new optional parameter does not change the version, so a client written against 1.7 keeps working as the API grows.
| Version | Swagger | Status | End of life |
|---|---|---|---|
| 1.7 | V1.7 | Current | — |
| 1.6 | V1.6 | Deprecated | Migrate |
| 1.5 | V1.5 | Deprecated | Migrate |
| 1.4 | V1.4 | Deprecated | Migrate |
| 1.3 | V1.3 | Deprecated | As soon as possible |
| 1.2 | V1.2 | Deprecated | As soon as possible |
| 1.1 | V1.1 | Deprecated | As soon as possible |
| 1.0 | V1 | Deprecated | As soon as possible |
Selecting a version
The version travels in a request header, not in the URL:
Api-Version: 1.7
Golden rule
Send Api-Version on every call, pinned to the version you developed against.
Omitting the header means "give me the latest", so the day a new version ships, your integration silently changes behaviour. Pinning it turns a future breaking change into a migration you schedule, instead of an incident you discover.
Swagger UI adds the header for you, which is why a call that works there can behave differently from your own client that omits it.
Where to go next
New here? Getting started goes from nothing to a data point you can read back, in six
curl calls.
Getting started — token, structure, first push, first read.
Connect to the API — credentials, scopes, tokens, troubleshooting.
Querying the API — entity chain, filters, the full GET /data reference.
Reference data — where every *TypeId and unitId comes from.
Recipes — exports, silent meters, idempotent sync, corrections.
.NET client — the Opinum.DataHub.Client package.
Python client — a small client built on requests.
Documentation changelog — how this documentation is versioned.