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

# Lumenaza API Reference: Overview and Conventions

> Complete reference for the Lumenaza API: base URLs, authentication, pagination, date formats, and resource groups.

The Lumenaza API is a **RESTful HTTP API** that lets you manage energy consumers, producers, contracts, prices, market data, and more within the Lumenaza platform. All endpoints are served under the `/v3/` path prefix and communicate exclusively using **JSON** — both request bodies and response payloads.

Key conventions:

* All request bodies must be encoded as JSON with `Content-Type: application/json`.
* All responses are JSON objects or arrays (except `204 No Content`).
* HTTP verbs follow standard REST semantics: `GET` (read), `POST` (create), `PUT`/`PATCH` (update), `DELETE` (remove).

***

## Base URLs

| Environment | Base URL |
| - | - |
| **Production** | `https://api.lumenaza.de/` |
| **Test** | `https://api.test.lumenaza.de/` |

All endpoint paths in this reference are relative to the base URL. For example, the full URL for `GET /v3/consumers/` in production is:

```
https://api.lumenaza.de/v3/consumers/
```

Use the **test environment** for integration development and sandbox testing. Data in the test environment is isolated from production.

***

## Authentication

Every request must carry a valid **Bearer token** in the `Authorization` header:

```http theme={null}
Authorization: Bearer <token>
```

Tokens are issued by Lumenaza. Requests without a valid token receive a `401 Unauthorized` response. Tokens should be treated as secrets — never expose them in client-side code or version control.

<Note>
  If your token has expired or is invalid, the API returns `401 Unauthorized`. Contact Lumenaza support to rotate or reissue credentials.
</Note>

***

## Pagination

List endpoints may return paginated results in one of two styles:

### Envelope-style pagination

Some endpoints return a JSON envelope object with the following fields:

| Field | Type | Description |
| - | - | - |
| `count` | integer | Total number of records matching the query |
| `next` | string \| null | URL of the next page, or `null` if on last page |
| `previous` | string \| null | URL of the previous page, or `null` if on first |
| `results` | array | Array of resource objects for the current page |

### Limit/offset pagination

Other endpoints accept `limit` and `offset` as query parameters:

| Parameter | Type | Description |
| - | - | - |
| `limit` | integer | Maximum number of records to return |
| `offset` | integer | Number of records to skip before returning results |

Combine both to page through large datasets:

```
GET /v3/consumers/?limit=50&offset=100
```

***

## Date and Time

All date-time values in request bodies and response payloads are expressed in **UTC** using the **ISO 8601** format:

```
YYYY-MM-DDTHH:MM:SSZ
```

**Example:** `2024-01-15T00:00:00Z`

Plain date fields (e.g. `sepa_date`, `order_date`) use the `YYYY-MM-DD` format without a time component.

<Warning>
  Submitting date-times in local time or with non-UTC offsets may cause unexpected behaviour or validation errors. Always normalise to UTC before sending.
</Warning>

***

## API Version

The current API version is **v3**. The version is embedded in every endpoint path:

```
/v3/<resource>/
```

***

## Resource Groups

The API is organised into the following resource groups (tags):

| Group | Description |
| - | - |
| `consumers` | Register, retrieve, update, and manage energy consumers |
| `producers` | Manage energy producers and feed-in data |
| `community` | Community energy sharing and allocation |
| `prices` | Tariff and pricing information |
| `master_data` | Master data for contracts and metering points |
| `user_documents` | Upload and retrieve consumer-facing documents |
| `marketpartners` | Manage market partner (DSO/supplier) relationships |
| `files` | Generic file upload and download |
| `validation` | Address, IBAN, and metering point validation utilities |

***

## Rate Limiting

Rate limiting policies are **not publicly specified**. If your integration requires guaranteed throughput or you are experiencing throttling, contact [Lumenaza support](https://www.lumenaza.de/) to discuss your requirements.

***

## Explore the API

<CardGroup cols={2}>
  <Card title="Errors & Troubleshooting" icon="triangle-exclamation" href="/api-reference/errors">
    HTTP status codes, field-level validation errors, and debugging tips.
  </Card>

  <Card title="List Consumers" icon="list" href="/api-reference/consumers/list">
    Retrieve a list of consumers or look up a single consumer by ID.
  </Card>

  <Card title="Create Consumer" icon="user-plus" href="/api-reference/consumers/create">
    Register a new consumer and contract via a single POST request.
  </Card>

  <Card title="Producers" icon="bolt" href="/api-reference/producers/list">
    Manage energy producers connected to the platform.
  </Card>

  <Card title="Prices" icon="tag" href="/api-reference/prices/epex">
    Query tariff and pricing data for products.
  </Card>

  <Card title="Master Data" icon="circle-check" href="/api-reference/master-data/changes">
    Manage address, bank data, and other customer master data changes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.