De REST API gebruiken

De MoneyLights REST API laat jouw systemen de gegevens van je organisatie lezen en onderhouden: transacties, leveranciers, klanten, projecten, categorieën en cashflow. Je authenticeert 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> werkt 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 je 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 verschillende dingen zeggen, vertrouw dan op het document. Je kunt het doorgeven aan een clientgenerator of het 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 of project toewijzen, ze splitsen over mensen (allocaties), 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 onbeheerd moet nemen — die acties blijven voorbehouden aan de app.

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

Snelheidslimieten

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

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

De organisatiebrede limiet per minuut is de limiet waar je omheen moet ontwerpen. Het is hetzelfde getal als de limiet per sleutel, dus één sleutel die op volle snelheid draait kan de minuut van de hele organisatie verbruiken — extra sleutels leveren geen extra doorvoer op. Als je meerdere integraties hebt, spreid hun verzoeken over de tijd.

Elke respons bevat X-RateLimit-Limit en X-RateLimit-Remaining. Een 429 bevat Retry-After in seconden — respecteer het; onmiddellijk opnieuw proberen kan een korte snelheidslimiet in een storing veranderen.

Fouten

Weigeringen dragen een stabiele code waarop jouw integratie kan reageren. De codes die je werkelijk zult tegenkomen:

Code	Betekenis
`api_key_invalid`	De sleutel is verkeerd gevormd of onbekend, of het geheim ervan is onjuist
`api_key_expired`	Verlopen — maak een nieuwe sleutel aan
`api_key_revoked`	De sleutel is ingetrokken, of het oude geheim is gebruikt nadat het rotatievenster gesloten was
`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 dat geen sleutel verzendt, krijgt een eenvoudige 401 met een lege body en geen foutcode. Als je dat ziet, is de sleutelheader niet verzonden.

Datumbereiken

GET /api/cashflow/overview accepteert een optionele dateFrom en dateTo. Als ze worden weggelaten, is dateFrom standaard 1 januari van het huidige jaar en dateTo vandaag (beide UTC). Het retourneert 400, geen leeg overzicht, wanneer:

een datum niet kan worden geparst (bijvoorbeeld 2026-13-01);
dateFrom na dateTo ligt;
alleen dateTo wordt verzonden en die eerder is dan de standaardstart (1 januari van het huidige UTC-jaar) — stuur ook een dateFrom;
alleen dateFrom wordt verzonden en die later is dan vandaag — stuur ook een dateTo.

Goed om te weten

Je sleutel bereikt precies één organisatie — de organisatie waarvoor hij is uitgegeven. Hij kan niet op een andere worden gericht.
Gebruikscijfers zijn bij benadering. Gebruik “Laatst gebruikt” en het aantal verzoeken om te controleren of een sleutel nog in gebruik is, niet voor facturering.
Geef de voorkeur aan de API voor gegevensstromen, en de MCP-server wanneer een AI-assistent de verzoeken doet — dezelfde inloggegevens, dezelfde scopes.