The UI is a client like any other.

The constitutional rule: nothing the portals can do exists outside the public API. There is no private endpoint, no internal fast path, no feature that arrives in the UI first — so nothing you build on the API is second-class, by construction.

One surface

SPEC 13 §1

OpenAPI, published and versioned. Responses carry their provenance.

The API is specified in OpenAPI, versioned with the product, and the portals are held to it in CI — a portal feature that needs an endpoint the spec does not have fails the build. Query responses include the same provenance the UI shows: pct_good, lossy ranges, manual origins. Your script learns about the outage at the same moment the control room does.

Where pct_good comes from Or skip the API: cold tier is open Parquet

GET /v1/query · python-requests

r = requests.get(
  "https://hist.site-east.example/v1/query",
  params={"expr": "avg(motor_power_kw)",
          "asset": "cr-102",
          "window": "1h"},
  headers={"Authorization": f"Bearer {tok}"})

r.json()
{
  "value": 741.86,
  "unit": "kW",
  "window": "2026-07-14T12:00Z/PT1H",
  "provenance": {
    "pct_good": 96.4,
    "lossy_ranges": 2,
    "manual_origin": 1
  }
}

the number never travels without its confession — not even over HTTP.

ordctl

SPEC 13 §2

The CLI for scripting, CI and the 2 a.m. question.

ordctl wraps the same public API — nothing more, verifiably. Output is plain text for humans, JSON or Parquet for pipelines, and exit codes behave, so it composes with cron, CI and whatever your site already runs. Template changes, lifecycle policies and token grants can all be applied from version-controlled files.

$ ordctl series list --asset cr-102

every series on an asset, with source and unit

$ ordctl query 'avg(motor_power_kw)' --window 1h --format parquet

aggregates straight into a pipeline, provenance columns included

$ ordctl template apply crusher_v3.yaml --dry-run

fleet-wide changes from version control, previewed first

Service tokens

SPEC 10 §6

Allow-only scopes. A token states what it can do, and that is the whole list.

Service tokens carry an explicit allow list — read these series, on these assets, over this span — and nothing else. There are no deny rules to reason about and no default grants to forget. Every token has an owner, an expiry and an audit trail, and rotating one is a single ordctl command in your CI.

The full security model

service token · energy-report-ci

scoperead: site-east/energy/*

assets42 · meter tree only

write accessnone — not granted

expires2026-10-01 · rotation in CI

ownerj.wallace

last used2026-07-14 05:00:03

what is not on the list does not exist for this token. audits read the grant, not the code.

The OpenAPI spec, the ordctl reference and the token model are documented in full — no NDA, no developer programme.

Read the API docs Query the demo API