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.

​
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.