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 a knowledge stamp k — the observed ingest arrival, when this platform actually stored the value (measured, never synthesized from a declared publication delay). Revisions are archived, never overwritten. Pass as_of=<ts> to any data query to reconstruct exactly what the API had served at that instant. History bulk-backfilled at platform inception carries its backfill arrival, so as_of earlier than capture honestly returns nothing.
• 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).
• Delta pulls. Pass since=<watermark> to /data or /bids to receive only values that arrived after it — new points, revisions of old periods and backfilled gap-heals in one response. Poll with your last k instead of re-downloading windows; composes with as_of (since < arrival ≤ as_of).

REST API

Range caps: 92 days per request (2 days for tick series, 7 for bid stacks); /v1/export allows a whole year per file within a value budget. All error detail strings say what to do instead.

# point-in-time (backtest-grade): the day-ahead curve as the API served it 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"

# delta pull: only what arrived after my watermark (new points AND revisions)
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&since=2026-07-10T12:00:00Z"

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 — observations, forecasts, ticks and bid stacks alike. Payload lists the affected series+zones — fetch fresh values via /data (pass since= for just the delta) or /latest. Events are named: use addEventListener, not onmessage.

Every update carries an event id. When the connection drops, EventSource reconnects with Last-Event-ID automatically and the missed events (up to ~24 h) are replayed in order — nothing is lost in the gap. A reset event means the gap could not be proven contiguous: do one full refresh, then continue live. That pull-after-update loop with a since= watermark is the intended terminal integration.

const es = new EventSource("{ORIGIN}/v1/stream?api_key=" + KEY);
es.addEventListener("update", (ev) => {
  const { series, max_valid_time } = JSON.parse(ev.data);
  // ev.lastEventId = replay cursor (sent back automatically on reconnect)
  // [{series_key: "imbalance_price", zone: "EE"}, ...]
});
es.addEventListener("reset", () => {/* replay gap too old — refetch in full */});
es.addEventListener("heartbeat", () => {/* every 30 s, keeps proxies open */});

Connect an AI client (MCP)

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 come back as compact CSV-in-text, resampled to ≤300 points. Pick your client below and swap YOUR_KEY for the key you were issued. The agent discovers series and semantics on its own, so you can just ask "compare the latest ECMWF vs GFS wind forecast for LV".

Claude Desktop — easiest for most people. Needs Node.js installed. Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then fully quit and reopen the app:

{
  "mcpServers": {
    "lowerflower": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "{ORIGIN}/mcp/?api_key=YOUR_KEY"]
    }
  }
}

claude.ai (web) — no install, needs a paid plan. Settings → Connectors → Add custom connector, set Authentication: None, and paste this URL (the key rides in the URL, so leave auth off):

{ORIGIN}/mcp/?api_key=YOUR_KEY

Claude Code — the terminal CLI, uses a real header:

claude mcp add -s user --transport http lowerflower {ORIGIN}/mcp/ \
  --header "X-API-Key: YOUR_KEY"

Self-hosted / local checkout — stdio, no key needed (talks straight to your DB):

claude mcp add lowerflower -- uv run --directory ~/Desktop/E2E_LFL lfl mcp

One-shot context (any model, no MCP) — the whole platform as a single plain-text file: concepts, every endpoint, and every series with its upstream-id mappings. Fetch it once and paste or attach it:

curl -H "X-API-Key: $LFL_KEY" {ORIGIN}/llms.txt > lfl-context.txt

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."}