Quickstart

Everything is keyed. Pass the key in the X-API-Key header (or ?api_key= for SSE, where headers aren't possible).

# who am I — identity, entitlements, limits, today's usage
curl -H "X-API-Key: $LFL_KEY" {ORIGIN}/v1/me

# discover series (AI-first metadata; filter with ?q= ?category= ?zone= ?source=)
curl -H "X-API-Key: $LFL_KEY" "{ORIGIN}/v1/catalog?q=imbalance"

# fetch data (UTC ISO8601; timestamps label period START; end is exclusive)
curl -H "X-API-Key: $LFL_KEY" \
  "{ORIGIN}/v1/series/imbalance_price/data?zone=EE&start=2026-07-10T00:00:00Z&end=2026-07-11T00:00:00Z"

The machine-readable OpenAPI schema lives at {ORIGIN}/openapi.json — keyed like everything else, so fetch it with the X-API-Key header.

Concepts

• Bi-temporal storage. Every value carries valid_time (the delivery interval it describes) and knowledge_time (when it became knowable). Revisions are archived, never overwritten. Pass as_of=<ts> to any data query to reconstruct exactly what was knowable at that instant.
• Forecast vintages. Forecasts keep every run (issued_at). Default = best-known value per period; issue_time=latest returns the newest coherent curve; an exact timestamp returns that vintage. List runs via /v1/series/{id}/runs.
• Dimensions. zone (EE/LV/LT/…) and entity (corridor, station, fuel) are query parameters, never part of the series id. Direction and model family are part of the id (afrr_lmp_up, wind_forecast_ecmwf).
• Sources. A series can be carried by several upstreams (e.g. BTD primary, ENTSO-E secondary). You get the first source your key is entitled to.
• Storage shapes. Scalar observations, forecasts, native 4-second ticks (capped at 2 days/request), and bid stacks (query /bids, not /data).

REST API

Range caps: 92 days per request (2 days for tick series, 7 for bid stacks). Split longer ranges into chunks. All error detail strings say what to do instead.

# point-in-time (backtest-grade): the day-ahead curve as it was knowable at 09:00
curl -H "X-API-Key: $LFL_KEY" \
  "{ORIGIN}/v1/series/day_ahead_price/data?zone=EE&start=2026-07-10T00:00:00Z&end=2026-07-11T00:00:00Z&as_of=2026-07-10T09:00:00Z"

# one coherent forecast run instead of the best-known splice
curl -H "X-API-Key: $LFL_KEY" \
  "{ORIGIN}/v1/series/wind_forecast_ecmwf/data?zone=LV&start=2026-07-11T00:00:00Z&end=2026-07-13T00:00:00Z&issue_time=latest"

Series reference

Every series id the API serves, with what it is and when new data arrives. Click a row to open the series. Full metadata (quirks, usage hints, entities) via GET /v1/catalog/{id}.

Live push (SSE)

One long-lived connection; update events fire the moment ingestion writes a value that actually changed. Payload lists the affected series+zones — fetch fresh values via /data or /latest. Events are named: use addEventListener, not onmessage.

const es = new EventSource("{ORIGIN}/v1/stream?api_key=" + KEY);
es.addEventListener("update", (ev) => {
  const { series, max_valid_time } = JSON.parse(ev.data);
  // [{series_key: "imbalance_price", zone: "EE"}, ...]
});
es.addEventListener("heartbeat", () => {/* every 30 s, keeps proxies open */});

MCP for AI agents

The same data over the Model Context Protocol — 7 tools (catalog search, series description, data with auto-downsampling, latest values, forecast runs, source health). Values are returned as compact CSV-in-text, resampled to ≤300 points.

# Claude Code / Claude Desktop, hosted instance (streamable HTTP — note the trailing slash)
claude mcp add --transport http lfl-power-data {ORIGIN}/mcp/ \
  --header "X-API-Key: $LFL_KEY"

# self-hosted / local checkout (stdio)
claude mcp add lfl-power-data -- uv run --directory ~/Desktop/E2E_LFL lfl mcp

Then ask things like "compare the latest ECMWF vs GFS wind forecast for LV" — the agent discovers series and semantics through the catalog tools.

Access, limits & licensing

• Keys. lfl_<key_id>_<secret>; the secret is stored hashed and shown once at creation. Keys are issued by the operator only — request one from the launch page ("Request access") and you will hear back at the contact you give. Lifecycle via CLI: lfl keys create --name alice [--sources btd,entsoe] [--expires-days 90], lfl keys list, lfl keys revoke <key_id>. Revocation is immediate.
• Source entitlements. Each key may be restricted to specific upstreams. Syspower (Volue/SKM) data is contractually licensed — it is only granted to keys whose owners hold their own license. Unentitled requests get a 403 with the reason; multi-source series transparently fall back to a source you may read; the SSE stream only shows you events for series you can access. Check yours at /v1/me.
• Rate limit. 600 requests/minute per key (per-key override possible). On 429, honor Retry-After.
• Metering. Requests and points served are recorded per key per day — visible in /v1/me as usage_today.
• Scopes. read for data; admin unlocks the Admin console and the /v1/admin/keys endpoints — create keys, edit source access, change rate limits, revoke. Every mutation is written to the audit log.

Errors

All errors are RFC 9457 application/problem+json with a detail written for self-correction:

{"type": "about:blank", "title": "Not entitled", "status": 403,
 "detail": "This key is not entitled to source(s) ['syspower'] ... contact the operator."}