Utiliser l'API REST

L’API REST de MoneyLights permet à tes propres systèmes de lire et de maintenir les données de ton organisation : transactions, fournisseurs, clients, projets, catégories et flux de trésorerie. Tu t’authentifies avec une clé API.

Appeler l’API

Envoie ta clé dans l’en-tête X-API-Key :

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

Authorization: ApiKey <key> fonctionne aussi. Authorization: Bearer <key> ne fonctionne pas — Bearer appartient à la session du navigateur. Ne mets jamais la clé dans l’URL : de telles requêtes sont refusées avant d’atteindre quoi que ce soit.

La référence lisible par machine

La liste complète et toujours à jour de ce que ta clé peut atteindre est le document OpenAPI public :

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

Il est généré à partir de l’application en cours d’exécution et liste exactement les endpoints publiés, chacun annoté avec la portée qu’il nécessite (x-required-scope). Si ce guide et ce document disent des choses différentes, fais confiance au document. Tu peux l’utiliser pour un générateur de client ou l’importer dans un outil API.

Ce qui est accessible — et ce qui ne l’est pas

Seuls les endpoints qui ont été explicitement publiés font partie de l’API publique. La règle directrice est enrichir et maintenir, jamais détruire :

Tu peux lister et filtrer les transactions, leur assigner une catégorie, un fournisseur, un client ou un projet, les répartir entre des personnes (allocations), et créer ou mettre à jour des fournisseurs, clients, projets et catégories.
Tu ne peux pas supprimer un fournisseur, un client, un projet ou une catégorie via l’API. Supprimer un enregistrement auquel d’autres enregistrements font référence est une décision qu’un script ne devrait pas prendre sans surveillance — ces actions se font dans l’application.

Les connexions bancaires, la facturation, la gestion d’équipe et la gestion des clés API ne sont jamais accessibles avec une clé, quelles que soient les portées dont elle dispose.

Limites de taux

Trois limites s’appliquent, et une requête doit satisfaire à toutes :

Plan	Lectures/min par clé	Écritures/min par clé	Requêtes/min par organisation	Par jour, par organisation
Team	120	30	120	10 000
Enterprise	600	150	600	100 000

La limite par minute au niveau de l’organisation est celle autour de laquelle concevoir. C’est le même nombre que la limite par clé, donc une clé fonctionnant à plein régime peut consommer toute la minute de l’organisation — ajouter des clés n’achète pas de capacité supplémentaire. Si tu as plusieurs intégrations, étale leurs requêtes dans le temps.

Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining. Un 429 porte Retry-After en secondes — respecte-le ; réessayer immédiatement peut transformer une courte limite de taux en une panne.

Erreurs

Les refus portent un code stable sur lequel ton intégration peut agir. Ceux que tu rencontreras réellement :

Code	Signification
`api_key_invalid`	La clé est malformée ou inconnue, ou son secret est incorrect
`api_key_expired`	Passé sa date d’expiration — crée une nouvelle clé
`api_key_revoked`	La clé a été révoquée, ou l’ancien secret a été utilisé après la fermeture de sa fenêtre de rotation
`api_key_scope_missing`	La clé n’a pas la portée dont cet endpoint a besoin
`api_key_endpoint_not_published`	L’endpoint ne fait pas partie de l’API publique
`api_key_rate_limited`	Au-delà d’une limite — respecte `Retry-After`

Une requête qui n’envoie aucune clé obtient un simple 401 avec un corps vide et aucun code d’erreur. Si tu vois cela, l’en-tête de clé n’a pas été envoyé.

Plages de dates

GET /api/cashflow/overview prend un dateFrom et un dateTo optionnels. S’ils sont omis, dateFrom vaut par défaut le 1er janvier de l’année en cours et dateTo aujourd’hui (tous deux en UTC). Il retourne 400, et non un aperçu vide, lorsque :

une date ne peut pas être analysée (par exemple 2026-13-01) ;
dateFrom est postérieur à dateTo ;
seul dateTo est envoyé et il est antérieur au début par défaut (1er janvier de l’année UTC en cours) — envoie aussi un dateFrom ;
seul dateFrom est envoyé et il est postérieur à aujourd’hui — envoie aussi un dateTo.

Bon à savoir

Ta clé atteint exactement une organisation — celle pour laquelle elle a été émise. Elle ne peut pas être dirigée vers une autre.
Les chiffres d’utilisation sont approximatifs. Utilise “Dernière utilisation” et le nombre de requêtes pour vérifier si une clé est toujours utilisée, pas pour la facturation.
Privilégie l’API pour les flux de données, et le serveur MCP lorsqu’un assistant IA effectue les requêtes — même identifiant, mêmes portées.