Verwendung der REST-API

Die MoneyLights REST-API ermöglicht es deinen eigenen Systemen, die Daten deiner Organisation zu lesen und zu verwalten: Transaktionen, Anbieter, Kunden, Projekte, Kategorien und Cashflow. Du authentifizierst dich mit einem API-Schlüssel.

Aufrufen der API

Sende deinen Schlüssel im X-API-Key-Header:

GET /api/transactions HTTP/1.1
Host: api.moneylights.app
X-API-Key: ml_sk_<key-id>_<secret>

Authorization: ApiKey <key> funktioniert ebenfalls. Authorization: Bearer <key> funktioniert nicht — Bearer gehört zur Browsersitzung. Setze den Schlüssel niemals in die URL: solche Anfragen werden abgelehnt, bevor sie irgendetwas erreichen.

Die maschinenlesbare Referenz

Die vollständige, immer aktuelle Liste dessen, was dein Schlüssel erreichen kann, ist das öffentliche OpenAPI-Dokument:

GET https://api.moneylights.app/api/public/openapi.json

Es wird aus der laufenden Anwendung generiert und listet genau die veröffentlichten Endpunkte auf, jeder mit dem erforderlichen Scope annotiert (x-required-scope). Wenn diese Anleitung und das Dokument unterschiedliche Dinge sagen, vertraue dem Dokument. Du kannst es einem Client-Generator zuführen oder in ein API-Tool importieren.

Was erreichbar ist — und was nicht

Nur Endpunkte, die ausdrücklich veröffentlicht wurden, sind Teil der öffentlichen API. Die leitende Regel ist bereichern und verwalten, niemals zerstören:

Du kannst Transaktionen auflisten und filtern, ihnen eine Kategorie, einen Anbieter, einen Kunden oder ein Projekt zuweisen, sie auf Personen aufteilen (Zuordnungen) und Anbieter, Kunden, Projekte und Kategorien erstellen oder aktualisieren.
Du kannst nicht einen Anbieter, Kunden, ein Projekt oder eine Kategorie über die API löschen. Das Entfernen eines Datensatzes, auf den andere Datensätze verweisen, ist eine Entscheidung, die ein Skript nicht unbeaufsichtigt treffen sollte — diese Aktionen bleiben der App vorbehalten.

Bankverbindungen, Abrechnung, Teamverwaltung und API-Schlüsselverwaltung sind niemals mit einem Schlüssel erreichbar, unabhängig von den Scopes, die er hat.

Ratenlimits

Drei Limits gelten, und eine Anfrage muss alle erfüllen:

Plan	Lesevorgänge/Min. pro Schlüssel	Schreibvorgänge/Min. pro Schlüssel	Anfragen/Min. pro Organisation	Pro Tag, pro Organisation
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

Das organisationsweite Limit pro Minute ist das, um das herum du planen solltest. Es ist die gleiche Zahl wie das Limit pro Schlüssel, sodass ein Schlüssel, der voll ausgelastet ist, die Minute der gesamten Organisation verbrauchen kann — zusätzliche Schlüssel erhöhen den Durchsatz nicht. Wenn du mehrere Integrationen hast, verteile ihre Anfragen über die Zeit.

Jede Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining. Ein 429 trägt Retry-After in Sekunden — halte dich daran; sofortiges Wiederholen kann ein kurzes Ratenlimit in einen Ausfall verwandeln.

Fehler

Ablehnungen tragen einen stabilen code, auf den deine Integration reagieren kann. Die, denen du tatsächlich begegnen wirst:

Code	Bedeutung
`api_key_invalid`	Der Schlüssel ist fehlerhaft oder unbekannt, oder sein Geheimnis ist falsch
`api_key_expired`	Nach dem Ablaufdatum — erstelle einen neuen Schlüssel
`api_key_revoked`	Der Schlüssel wurde widerrufen, oder das alte Geheimnis wurde verwendet, nachdem sein Rotationsfenster geschlossen war
`api_key_scope_missing`	Der Schlüssel hat nicht den Scope, den dieser Endpunkt benötigt
`api_key_endpoint_not_published`	Der Endpunkt ist nicht Teil der öffentlichen API
`api_key_rate_limited`	Über einem Limit — halte `Retry-After` ein

Eine Anfrage, die keinen Schlüssel sendet, erhält eine einfache 401 mit einem leeren Body und ohne Fehlercode. Wenn du das siehst, wurde der Schlüssel-Header nicht gesendet.

Datumsbereiche

GET /api/cashflow/overview akzeptiert optional dateFrom und dateTo. Fehlen sie, wird dateFrom standardmäßig auf den 1. Januar des aktuellen Jahres und dateTo auf heute (beide UTC) gesetzt. Es gibt 400 zurück, keine leere Übersicht, wenn:

ein Datum nicht geparst werden kann (zum Beispiel 2026-13-01);
dateFrom nach dateTo liegt;
nur dateTo gesendet wird und es früher ist als der Standardstart (1. Januar des aktuellen UTC-Jahres) — sende auch ein dateFrom;
nur dateFrom gesendet wird und es später als heute ist — sende auch ein dateTo.

Gut zu wissen

Dein Schlüssel erreicht genau eine Organisation — die, für die er ausgestellt wurde. Er kann nicht woanders hin gerichtet werden.
Nutzungszahlen sind Näherungswerte. Verwende “Zuletzt verwendet” und die Anfrageanzahl, um zu überprüfen, ob ein Schlüssel noch in Gebrauch ist, nicht für die Abrechnung.
Bevorzuge die API für Datenflüsse und den MCP-Server wenn ein KI-Assistent die Anfragen stellt — dieselben Anmeldeinformationen, dieselben Scopes.