De REST API gebruiken

De MoneyLights REST API stelt jouw systemen in staat om de gegevens van jouw organisatie te lezen en te onderhouden: transacties, leveranciers, klanten, projecten, categorieën en cashflow. Je authenticateert met een API-sleutel.

De API aanroepen

Stuur je sleutel in de 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> werkt ook. Authorization: Bearer <key> doet niet — Bearer behoort tot de browsersessie. Zet de sleutel nooit in de URL: dergelijke verzoeken worden geweigerd voordat ze iets bereiken.

De machine-leesbare referentie

De complete, altijd actuele lijst van wat jouw sleutel kan bereiken is het openbare OpenAPI-document:

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

Het wordt gegenereerd vanuit de draaiende applicatie en geeft precies de gepubliceerde endpoints weer, elk geannoteerd met de scope die het vereist (x-required-scope). Als deze gids en dat document ooit niet overeenkomen, heeft het document gelijk. Je kunt het gebruiken voor een clientgenerator of importeren in een API-tool.

Wat is bereikbaar — en wat niet

Alleen endpoints die expliciet zijn gepubliceerd maken deel uit van de openbare API. De leidende regel is verrijk en onderhoud, vernietig nooit:

Je kunt transacties opsommen en filteren, ze een categorie, leverancier, klant, project of persoon toewijzen, en leveranciers, klanten, projecten en categorieën aanmaken of bijwerken.
Je kunt niet een leverancier, klant, project of categorie via de API verwijderen. Het verwijderen van een record waar andere records naar verwijzen is een beslissing die een script niet onbewaakt moet nemen — die acties leven in de app.

Bankverbindingen, facturering, teambeheer en API-sleutelbeheer zijn nooit bereikbaar met een sleutel, ongeacht welke scopes het heeft.

Snelheidslimieten

Er gelden drie limieten, en een verzoek moet aan al deze voldoen:

Plan	Lezingen/min per sleutel	Schrijvingen/min per sleutel	Verzoeken/min per organisatie	Per dag, per organisatie
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

De organisatie-brede limiet per minuut is de limiet waar je omheen moet ontwerpen. Het is hetzelfde nummer als de limiet per sleutel, dus één sleutel die op volle snelheid draait kan de hele organisatie’s minuut verbruiken — extra sleutels kopen geen doorvoer. Als je meerdere integraties draait, zorg dan voor een goede spreiding.

Elke respons bevat X-RateLimit-Limit en X-RateLimit-Remaining. Een 429 bevat Retry-After in seconden — respecteer dit; onmiddellijk opnieuw proberen is hoe een snelheidslimiet een storing wordt.

Fouten

Weigeringen bevatten een stabiele code waarop je kunt schakelen. De codes die je daadwerkelijk zult tegenkomen:

Code	Betekenis
`api_key_invalid`	Ongeldig, onbekend of verkeerd geheim
`api_key_expired`	Verlopen — maak een nieuwe sleutel aan
`api_key_revoked`	De sleutel is ingetrokken, of een geroteerd geheim is verlopen
`api_key_scope_missing`	De sleutel mist de scope die dit endpoint nodig heeft
`api_key_endpoint_not_published`	Het endpoint maakt geen deel uit van de openbare API
`api_key_rate_limited`	Boven een limiet — respecteer `Retry-After`

Een verzoek zonder sleutel krijgt een eenvoudige 401 zonder code — beschouw een lichaamloze 401 als “ik vergat de header”.

Goed om te weten

Jouw sleutel bereikt precies één organisatie — de organisatie waarvoor deze is uitgegeven. Het kan nergens anders naartoe worden gewezen.
Gebruikscijfers zijn indicatief. “Laatst gebruikt” en het aantal verzoeken beantwoorden de vraag “wordt dit nog gebruikt?”, niet factureringsvragen.
Geef de voorkeur aan de API voor gegevensstromen, en de MCP Server wanneer de aanroeper een AI-assistent is — dezelfde inloggegevens, dezelfde scopes.