> ## Documentation Index
> Fetch the complete documentation index at: https://docs.energy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Base URL, authentication and error semantics

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 **service URL** and **API key**. Send the key in the
`X-API-Key` header on every request:

```bash theme={null}
curl -H "X-API-Key: $NLEAD_API_KEY" https://<service-host>/v1/forecasts
```

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.

## Endpoints at a glance

| Endpoint                | Purpose                                 |
| ----------------------- | --------------------------------------- |
| `POST /v1/forecasts`    | Portfolio forecast for one delivery day |
| `PUT /v1/master-data`   | Market-location master data             |
| `POST /v1/metered-data` | Quarter-hourly metered values           |
| `POST /v1/profiles`     | Rolled-out load profiles per MGA        |
| `GET /health`           | Availability check (no key required)    |

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

## Errors

| Status | Meaning                                                                                                                           |
| ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing or wrong `X-API-Key`                                                                                                      |
| `422`  | Validation failure — wrong interval count, incomplete series, unknown control area, unmapped market location, or a malformed body |

Validation errors carry a `detail` message naming the offending series and
the rule it broke, for example:

```json theme={null}
{ "detail": "series[3] has 95 intervals, expected 96 for 2026-08-01" }
```