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> tut 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, die jeweils mit dem erforderlichen Scope (x-required-scope) annotiert sind. Wenn diese Anleitung und dieses Dokument jemals widersprüchlich sind, hat das Dokument recht. 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, ein Projekt oder Personen zuweisen und Anbieter, Kunden, Projekte und Kategorien erstellen oder aktualisieren.
Du kannst einen Anbieter, Kunden, ein Projekt oder eine Kategorie nicht ü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 leben in der App.

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 du herum planen solltest. Es ist die gleiche Zahl wie das pro-Schlüssel-Limit, sodass ein Schlüssel, der voll ausgelastet ist, die gesamte Minute der Organisation verbrauchen kann — das Hinzufügen von Schlüsseln erhöht nicht den Durchsatz. Wenn du mehrere Integrationen betreibst, taktiere sie.

Jede Antwort enthält X-RateLimit-Limit und X-RateLimit-Remaining. Ein 429 enthält Retry-After in Sekunden — halte dich daran; sofortiges Wiederholen ist der Weg, wie ein Ratenlimit zu einem Ausfall wird.

Fehler

Ablehnungen tragen einen stabilen code, auf den du umschalten kannst. Die, die du tatsächlich treffen wirst:

Code	Bedeutung
`api_key_invalid`	Fehlformatierter, unbekannter oder falscher Schlüssel
`api_key_expired`	Abgelaufen — erstelle einen neuen Schlüssel
`api_key_revoked`	Der Schlüssel wurde gesperrt oder ein rotierendes Geheimnis ist abgelaufen
`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 ohne überhaupt einen Schlüssel erhält ein einfaches 401 ohne Code — behandle ein körperloses 401 als “Ich habe den Header vergessen”.

Gut zu wissen

Dein Schlüssel erreicht genau eine Organisation — die, für die er ausgestellt wurde. Er kann nicht anderswohin gerichtet werden.
Nutzungszahlen sind indikativ. “Zuletzt verwendet” und die Anfrageanzahl beantworten die Frage “wird dies noch verwendet?”, nicht Abrechnungsfragen.
Bevorzuge die API für Datenflüsse und den MCP-Server wenn der Aufrufer ein KI-Assistent ist — dieselben Anmeldeinformationen, dieselben Scopes.