Skip to main content
The API is deliberately small: submit a portfolio forecast, or submit the master, metered and profile data the bridge builds a forecast from. The endpoint pages in this section are generated from the service’s OpenAPI specification.

​
Base URL and authentication

n:lead provides your API key separately. Send it in the X-API-Key header on every request:
api.energy.nlead.ch is the permanent entry point — it stays stable across releases and infrastructure changes. Keep it in configuration rather than hard-coded; every example here uses $NLEAD_BASE_URL so the same snippets work against any environment.
Keep the key secret and treat it as a credential for your portfolio data. GET /health needs no key and can be used for availability checks.

​
Sandbox key — develop without fear

n:lead can issue you a sandbox key alongside the production key. It reaches the same endpoints with the same payloads and returns the same validation errors, but the service forces every call into validate-only mode: nothing is stored, nothing reaches the market, whatever the payload says. Responses then carry status: "validated" instead of received/stored. Build and test the whole integration with the sandbox key; switch the configured key to the production one when you go live. No code change — the key is the switch. If your organisation issues OAuth2 client-credentials tokens, the API also accepts them instead of a key — Authorization: Bearer <token> — once your issuer is registered with n:lead. Both work side by side, so you can move across without a cutover.

​
Rate limits

Requests are limited per caller. Exceeding the limit returns 429 with a Retry-After header giving the seconds to wait; retry after that delay.

​
Endpoints at a glance

The status endpoint answers with a read-only report key (n:lead issues it separately from the data-delivery key): the communication state with one Netzbetreiber — Erstkontakt, PARTIN both ways, acknowledgments, Zuordnungsermächtigung per Bilanzierungsgebiet — and the derived overall status (complete, established, pending, rejected, contacted, none). Address the partner by MP-ID or by any of its MGA EICs. The dashboard endpoints answer with a dashboard key, again issued separately. It is read-only and opens the dashboard endpoints only, so it can sit on an office screen. For the charts and the screen page it may also be sent in the URL (?key=), since a picture or a screen’s browser cannot send a header; no other key is accepted there.

​
Conventions

  • Time: delivery days are calendar days in Europe/Berlin; series run from local midnight to local midnight with 96 / 92 / 100 quarter-hours depending on daylight saving.
  • Units: MW (average per quarter-hour) or MWH (energy per quarter-hour); metered data also accepts KWH.
  • Idempotency: re-sending the same delivery day replaces the previous submission; an identical payload changes nothing.
  • Safe testing: POST /v1/forecasts accepts "validate_only": true — the full validation runs and the acknowledgment comes back with status: "validated", but nothing is stored and nothing reaches the market. Use it to test your integration against the live service. With a sandbox key this is the behavior of every call, on every endpoint, enforced server-side.

​
Errors

Validation errors carry a detail message naming the offending series and the rule it broke, for example:
Every message the API can return is listed verbatim, with its fix, on the troubleshooting page.