Integration guide

What the service returns, how to verify it, and what to do when a check fails.

Try it without an account

Two commands, no key, no sign-up. This fetches a real signed record for a real GB 400 kV circuit from the same engine and the same signing key a customer gets, and verifies the Ed25519 signature on your machine.

curl -O https://lineclarity.com/static/verify_lineclarity.py
python verify_lineclarity.py

It prints the amps you should use, the signature result and the reason. Point it at your own account later with --key and --line; the code is the same either way, and it is about 150 lines you can read in full before you run it.

Quick start

curl -H "X-API-Key: $LC_KEY" https://lineclarity.com/api/v1/whoami
curl -H "X-API-Key: $LC_KEY" https://lineclarity.com/api/v1/lines
curl -H "X-API-Key: $LC_KEY" "https://lineclarity.com/api/v1/rating?line=PENW-400-01"

curl -O https://lineclarity.com/static/verify_lineclarity.py
python verify_lineclarity.py --key $LC_KEY --line PENW-400-01

The last command prints the amps you should use and why. If it says source: static, a check failed and your system should be doing the same thing.

Endpoints

Endpoint	Purpose
GET /api/v1/whoami	Confirm the key, list its scopes and lines
GET /api/v1/lines	Your registered circuits
GET /api/v1/rating?line=&format=&hours=&detail=	The live rating
GET /api/v1/planning?line=&year=	Replay 12 months of recorded weather — a look back, no OT link
GET /api/v1/points?line=	Stable point/tag map for commissioning
GET /api/v1/audit	Every value we served you
GET /api/v1/pubkey	The Ed25519 public key. Fetch once, pin it.

The record

{
  "schema": "lineclarity.rating.v1",
  "line": { "line_id": "PENW-400-01", "line_uid": "ln_…", "ext_ref": "NGET.PENW.400.CKT1",
            "conductor": "Zebra ACSR (quad)", "kv": 400, "lat": 53.75, "lon": -2.72, "t_max_c": 75, "pf": 1 },
  "issued_at": "2026-09-05T18:04:00Z",
  "valid_until": "2026-09-05T18:19:00Z",
  "ttl_s": 900,
  "sequence": 1417,                   // monotonic per line
  "prev_digest": "sha256:…",          // chains to the previous record
  "status": "OK",                     // OK | DEGRADED | FAILSAFE
  "rating_a": 1264.3,                 // the number you operate to
  "rating_mw": 875.9,
  "static_a": 1133.8,                 // the number you fall back to
  "static_basis": "gb_seasonal",      // gb_seasonal | worst_case | customer
  "sub_conductors": 4,                // bundle: rated per sub-conductor, multiplied
  "below_static": false,              // true when the weather is worse than your static assumes
  "route": { "basis": "route", "spans_modelled": 5, "length_km": 32.0, "binding_span": 0 },
  "conservatism": { "precip_probability_pct": 40, "rain_expected": false, ... },
  "hard_cap_a": 1400,
  "cap_applied": false,
  "operating_horizon_h": 6,           // operate on rows before this; later rows are advisory=true
  "horizon": [ { "t": "…", "rating_a": 1264.3, "rating_mw": 875.9, "aar_a": 1180.0, "advisory": false }, … ],
  "summary": { "avg_gain_pct": 11.5, "avg_extra_mw": 90.4 },
  "failsafe": { "static_a": 1133.8, "max_age_s": 1800, "on_expiry": "revert_to_static" },
  "signature": { "alg": "Ed25519", "key_id": "k1_…", "digest": "sha256:…", "value": "base64…" }
}

• rating_a is already safe to operate to as published; apply no margin of your own.
• static_basis says where static_a came from. Set your own static rating on the circuit and it becomes customer — always do this. Until you do, a GB circuit defaults to a GB seasonal rating (gb_seasonal) and anything else to a single worst-case figure (worst_case).
• aar_a is the ambient-adjusted rating — temperature only, no wind or solar. It is the conservative middle step between static and the full rating, and it is what a US operator needs to satisfy FERC Order 881 from the same feed.
• &detail=full adds ampacity_a and the hourly weather.
• Ratings round down to 0.1 A. Integral values are integers, so the signature verifies from JavaScript as well as Python.
• horizon[0] is the current hour; the rest is forecast.
• advisory / operating_horizon_h — how far ahead this is worth operating to, as opposed to looking at. On GB nodes the true rating moves about 3% in one hour, 9% over six and 19% over 48. It also stops getting worse after roughly a day, so a two-day-ahead rating describes the climate more than the weather. Rows past the horizon are still published and still signed, and marked advisory: true. Use them for scheduling and outage planning; re-rate on the near ones.
• Your own conductor. Our library carries GB ACSR (Zebra, Lynx, Panther, Wolf, Goat, Dog) and the common North American types. If yours is not there — GB reconductoring uses AAAC types we have not sourced — set cond_diameter_mm and cond_r20_ohm_km on the line from your own conductor register and we use those instead of guessing. We would rather ask than invent a resistance, because it scales the rating directly.
• sub_conductors — per phase. GB 400 kV is normally twin or quad, and a bundle carries about n times one sub-conductor, so rating a quad circuit as a single one understates it fourfold. Set it explicitly and it overrides whatever the conductor name implies. It is applied to the static baseline as well as the rating, so the uplift percentage does not move — only the amps and the megawatts. First order: it ignores the mutual heating between sub-conductors.
• route — the circuit is sampled at several points along its route and the rating is the worst span, because the same current flows through all of them. The IEEE-738 wind-direction factor is applied per segment: wind along a conductor cools it far less than wind across it. Send a route on the line (both endpoints is enough, a tower polyline is better) — without one we rate a single point at the worst-case wind angle and mark the record DEGRADED.
• below_static — true in the rare hours when the weather is worse than your static rating assumes, so the honest limit is below it. A GB seasonal static assumes 20 °C in summer; 2026 delivered 35 °C. In those hours your static rating is the optimistic one.
• conservatism — what we deliberately do not credit. Rain cools a conductor but IEEE-738 does not model it, and a forecast that says rain when it is dry would hand you capacity that is not there. So rain only ever tells you the published number is conservative. Same for gusts (we use sustained wind) and conductor height above the 10 m wind measurement.

Verify, then use

Four checks on every pull. Any failure → use static_a.

1. Signature. Ed25519 over the canonical JSON of the record without the signature member: keys sorted by code point, separators , and :, UTF-8, no NaN.
2. Freshness. Reject past valid_until, or older than failsafe.max_age_s.
3. Sequence. Must never go backwards. The same sequence with the same signature.digest is simply the record you already hold, re-served between recomputations — keep using it, that is the current answer. Reject a lower sequence, or the same sequence arriving with a different signature. Optionally chain on prev_digest to prove nothing was dropped.
4. Status. OK use it · DEGRADED usable, raise a low alarm · FAILSAFE the record already holds static.

Reference implementations: Python · JavaScript. Both expose one rating_to_use() returning the amps and the reason. Set hard_cap_a per line in the portal — we enforce it server-side, you enforce it again. Alarm on repeated static fallbacks, sequence gaps, or any status other than OK.

Formats

Add &format= to any rating URL.

Format	Kind	What you get
json	native	The signed record. The signature is defined over this form.
csv	native	One row per hour, for historians and studies.
pi	native	AVEVA/OSIsoft PI Web API streamset body.
cim	native	IEC 61970 RDF/XML: OperationalLimitSet + CurrentLimit.
dnp3	export	Point map + values for your outstation.
iccp	export	TASE.2 bilateral point list + values for your gateway.
modbus	export	Holding-register map, scaled uint16 big-endian.
points	config	Tag/index map, no values. Indices never move for a line.

Non-JSON responses carry the signature in X-LineClarity-* headers; verification is defined over the JSON form, so verify there and transform locally if you need assurance downstream. Tag names derive from your ext_ref. Quality maps OK → Good / ONLINE / valid, DEGRADED → Questionable / COMM_LOST / suspect, FAILSAFE → Bad / LOCAL_FORCED / held.

Authentication

X-API-Key: lc_live_…

One key per consuming system so you can revoke one without disturbing the rest; we store only a hash. Scopes: read:ratings, read:planning. Optional per key: a source-IP allowlist, and HMAC request signing with X-LC-Timestamp (±300s), a single-use X-LC-Nonce, and X-LC-Signature = base64 HMAC-SHA256 over method, path, timestamp, nonce and the SHA-256 of the body, newline separated.

The portal has no passwords: we send a one-time enrolment code, your browser generates a non-extractable P-256 key, and signing in means signing a single-use challenge. We store public keys only. Owners invite people and revoke devices; anyone signed in can mint a code for their own second machine, inheriting their role and circuits, and can sign their own device out.

Access control

Roles, per-person circuits, access end dates and key scoping are set in the portal and described on the security page. Two things that matter to an integrator:

• Keys inherit their creator's circuits. An engineer can only cut keys for circuits they hold, and a key minted without naming lines inherits those circuits.
• Dashboard reads are not pulls. Viewing the portal does not advance your feed's sequence numbers or appear in your audit trail as a served rating.

Errors and limits

Code	Meaning
401	Missing/invalid key or expired session. Repeated failures back off exponentially.
403	Missing scope, source IP not allowed, or account suspended.
404	Unknown line for this account. Line IDs are per-account.
429	Rate limited — back off. The feed allows 240 requests/minute per key.
502/503	Engine unavailable. Use static and retry. We never return an unsigned record.

Poll every 5–15 minutes per line; ttl_s states the intended interval, and polling faster returns the same record. Every feed response is Cache-Control: no-store.

How far ahead can you trust it?

The operational feed is a forecast, so it inherits forecast error. Measured on four GB nodes:

Input wrong by	Rating moves
wind direction ±30°	5.3%
wind speed −30%	3.2%
ambient +3 °C	1.2%

Wind direction is the input the rating is most sensitive to, not temperature. Our forecast inputs differ from the ERA5 reanalysis by about 5% on the rating on average and 20% at the 95th percentile. The hard cap is enforced on both sides, the fail-safe is unconditional, and anything past operating_horizon_h is marked advisory.

Planning studies

A planning study is not a forecast. It replays a year of archived, observed weather and asks what you would have had if the circuit had been rated dynamically through that year. Nothing is predicted. The only inductive step is assuming the next year resembles the last, and that is tested separately: across 41 GB site-years a node moved a median of 2.0 points between years and never showed no uplift.

curl -H "X-API-Key: $LC_KEY" \
  "https://lineclarity.com/api/v1/planning?line=PENW-400-01&year=2024&congestion_hours=1000&congestion_price_mwh=60"

A year of archived weather: average uplift, p5/p50 ampacity, hours above static, a monthly shape, and a constraint value. No operational connection, so nothing to review on the OT side — the usual starting point.

The money figure is arithmetic on assumptions you supply: extra MW × binding hours × price/MWh, in the currency you name. The "extra MW" is taken from the hours the circuit is actually constrained — the windiest decile for a GB circuit, the hottest decile elsewhere. assumptions.basis in the record says which was used. It is published as congestion_value_upper_bound_yr because it assumes every extra MW relieves the constraint for every binding hour, which no single circuit does — scale it by the share of the constraint your circuit actually carries, or use value_per_extra_mw_yr and supply your own MW. The capacity numbers are physics and stand on their own; the money number does not until someone runs a power flow.

What we don't do

• Speak DNP3, ICCP or Modbus on the wire — those formats are exports for the gateway you already run.
• Connect into your network. No push, no VPN, no agent, no callback.
• Take operational data. Line specifications only: conductor, route, voltage, temperature limit.
• Use sensors. Ratings come from public weather and the IEEE-738 standard.

Missing something you need? Ask.