The European Energy Data API

A single interface for European fundamentals

The Voltstack Data API exposes the same European energy fundamentals that power the Voltstack Analytics terminal. Every endpoint returns JSON over HTTPS, designed for two patterns: low-latency polling for live desks, and scheduled pulls for analytics pipelines. The API is read-only and spans four domains:

• Power — day-ahead prices across 11 bidding zones, cross-border physical flows, actual generation by fuel across 9 countries, and a real merit-order supply stack.
• Gas — country/aggregate storage, LNG send-out and inventory, and physical pipeline flows at major import points.
• History — settled day-ahead price history, derived realized volatility, gas-storage history with a real five-year band, LNG send-out history, and commodity benchmarks (Brent, WTI, Henry Hub, EU gas, coal).
• Carbon — EEX EUA primary-auction results, licensed and live in the terminal (a /v1 path follows); EUA/UKA spot and forward pricing stays ENTERPRISE
• Weather — temperature, wind and precipitation forecasts with heating/cooling degree days.

All endpoints sit under one versioned base path. The major version is pinned in the path; additive changes (new fields, new zones) ship without a version bump.

Base URL   https://api.voltstack.energy/v1
Protocol   HTTPS only (TLS 1.2+)
Format     application/json; charset=utf-8
Methods    GET (read-only)

The /v1 surface is read-only, and every call to it should carry a data API key. As at this revision the surface is key-gated in full: a request with no key is refused on every documented path, current feeds and history alike. Which paths will require a key in the longer run is being revised, and this revision does not state that. The revision before 1.5 described a keyless surface with the history endpoints as the single exception; that is not what is deployed, and rather than replace it with a per-path scope that is itself in flux, the claim stays withdrawn. Key every request: that holds whichever way the scope settles, and it is what an integration has to build against. Ask data@voltstack.energy before you rely on anything narrower.

A data API key is a token of the form vsk_live_<key_id>_<secret> — a ten-character public lookup handle and a forty-character secret, both base62. It is presented in the X-API-Key header; an Authorization: Bearer header carrying the same token is also accepted. Keys are issued on request at research@voltstack.energy. Server-side each key is a row carrying its own identity, so keys are issued, listed, rotated and deactivated individually and usage is attributed per key; a configured DATA_API_KEYS list is honoured alongside them as a break-glass path. Only the SHA-256 digest of the secret is held at rest, and comparison is constant-time, so a key cannot be recovered from the store and cannot be guessed by timing.

Every issued key also carries one or more scopes, fixed when the key is issued: history covers the settled-history endpoints under /v1/history, current covers every other documented path (live power, gas, weather and benchmark feeds), and all covers both. A valid key presented on an endpoint outside its scopes is refused with 403 and error: "insufficient-scope". This is a different refusal from the 401 above: the credential itself verified, the grant is what falls short, so re-presenting the same key cannot succeed. The refusal names the scope the endpoint requires and the scopes the key was granted; it never echoes the key. Keys honoured through the break-glass DATA_API_KEYS list carry no scope restriction. To extend an issued key's scopes, write to research@voltstack.energy.

# Keyed request
curl "https://api.voltstack.energy/v1/history/day-ahead?zone=DE_LU&from=2026-01-01&to=2026-07-01" \
  -H "X-API-Key: vsk_live_<key_id>_<secret>"

# A missing or unrecognised key returns 401:
{ "error": "api-key-required",
  "detail": "This endpoint requires a data API key in the X-API-Key header. Request one at research@voltstack.energy." }

# A valid key presented outside its scopes returns 403:
{ "error": "insufficient-scope",
  "detail": "This API key does not carry the 'history' scope required by this endpoint (granted: current). To extend the key's scopes, contact research@voltstack.energy." }

Every response is wrapped in a uniform envelope — the core of Voltstack's data-integrity model. Each payload declares whether the value is live upstream data or a transparent fallback, when it was sourced, and whether it was cached. Consumers never receive a silently stale or fabricated value.

{
  "source":   "entsoe",            // canonical upstream identifier
  "live":     true,                // true = real upstream; false = treat as fallback
  "data":     { /* domain payload */ },
  "fetchedAt": 1781622120092,       // epoch ms the value was obtained
  "cached":   false,               // served from the server-side TTL cache
  "reason":   null,                // when live=false: "no-token" | "upstream-error" | "rate-limited" | "disabled"
  "meta": {                        // per-payload provenance
    "upstream": "ENTSO-E Transparency (A44)",
    "unit": "EUR/MWh (zone currency)", "timezone": "UTC",
    "completeness": 0.998,          // [0,1] fraction of expected points arrived (history)
    "gaps": [],                      // timestamp ranges with missing data (history)
    "dataAgeSeconds": 642            // seconds since the persisted data last changed
  }
}

The dislocation surface: physical constraint and event data behind the price series. Field-level detail for every payload is in the Data Dictionary §14–25. None of these endpoints carries a simulated fallback — when an upstream has nothing, the envelope says so.

Server-side caching is matched to each upstream's true publication cadence — polling faster than the TTL simply returns the cached value with cached:true.

There is currently no per-key rate limit on the /v1 surface: the server-side TTL cache is the effective throttle, and polling faster than the TTL only returns cached values. Upstream back-off surfaces as 200 with live:false and reason:"rate-limited", never as a 429 from Voltstack. Fair use applies during early access.

A transport error is a non-2xx status; a data fallback is 200 with live:false. A request for a feed whose upstream is briefly unavailable still returns 200 with a reason, so pipelines degrade gracefully rather than break.

v1.8 · 2026-08-27: §03 documents key scopes (history, current, all) and the 403 refusal a valid key receives on an endpoint its scopes do not cover, with the served insufficient-scope body printed; §08 gains the matching 403 row and the 401 row now points the short-scope case at it. Documentation catch-up: the shipped gate already refused short-scoped keys this way, and no behaviour changed in this revision. v1.7 · 2026-08-09: the §06 de-bess entry said "Public, no auth", which contradicted §03 inside this document and was false against the shipped gate, measured 401 unkeyed on every documented /v1 path. Removed: no §06 entry now states its own access rule, because access is set for the surface and §03 is where it is stated. The de-bess/custom entry now says its Professional-plan requirement is additional to §03 rather than an alternative to it. v1.6 · 2026-08-08: the §08 401 row said "history endpoints only", which v1.5 left standing when §03 withdrew the same claim. Every documented /v1 path refuses a keyless request, current feeds included, so §08 now says so and §03 states the observed gating rather than staying silent on it. The "keyless /v1" wording in the v1.3 note below is superseded on both counts. v1.5 · 2026-08-08: §03 withdraws the keyless-surface scope claim, which production replaced, and documents the shipped key mechanics instead (vsk_live_ token format, per-key identity, hashed at rest); the 401 example now prints the body the service actually returns. §09 corrects gas storage to six countries and weather to sixteen regions, and the §06 weather line follows; in each case one served id had never been documented, and the data dictionary §7 and §27 now name it. v1.4 · 2026-07-31: document version and date published as machine-readable meta tags (voltstack-doc-version, voltstack-doc-updated) and printed in the page header; the PDF edition is served alongside the HTML at /docs/. v1.3 — 2026-07-31: authentication rewritten to the shipped key model (keyless /v1; X-API-Key on history endpoints); day-ahead and flows payload examples corrected to the served shapes; error and rate-limit semantics corrected; envelope lastGood, areaStatus and the real reason enum documented; EUA primary auctions and the RTE FR generation forecast added to coverage. Specification subject to change during early access. Field names and coverage reflect the platform as at 2026-07-31. © 2026 Voltstack.