API-v1-Referenz

Überblick

Die Manilo API ist eine JSON-REST-API, mit der du dasselbe Haushaltsbuch programmatisch verwaltest, das du auch in der iOS-App nutzt — Konten, Kategorien, Budgets, geteilte Gruppen und Transaktionen. Nutze sie, um Importer, Exporter, Sync-Brücken oder Dashboards zu bauen oder deine eigenen Automatisierungen zu betreiben.

• Basis-URL: https://api.manilo.app — die bisherige Basis-URL api.ledgy.app funktioniert weiterhin.
• Versions-Präfix: Alle Endpunkte in diesem Dokument liegen unter /api/v1/.
• Transport: Nur HTTPS. HTTP-Anfragen werden nicht akzeptiert.
• Encoding: JSON in Request- und Response-Bodys. UTF-8. camelCase als Feldnamen.
• Authentifizierung: Authorization: Bearer … bei jeder Anfrage.
• Cloud-Abo: Für jeden v1-Endpunkt erforderlich. Siehe Abo-Pflicht.

Schnellstart

Drei Schritte bis zu deiner ersten authentifizierten Anfrage.

1. Personal Access Token erstellen

1. Melde dich in deinem Manilo-Dashboard an und öffne Einstellungen → API-Zugriff.
2. Klicke auf + Neuer Token.
3. Gib dem Token einen aussagekräftigen Namen (z. B. „Zapier — wöchentlicher Export“), wähle die Scopes, die du brauchst (siehe Scopes), und lege optional ein Ablaufdatum fest.
4. Kopiere den Token. Er wird nur einmal angezeigt. Tokens beginnen mit dem Präfix lgpat_, gefolgt von 64 Hex-Zeichen.

Dieselbe Seite listet deine aktiven Tokens mit dem Zeitpunkt der letzten Nutzung und der Anzahl der Berechtigungen auf, blendet eine Warnung „Läuft in 30 Tagen ab“ ein und lässt dich jeden Token über das Papierkorb-Symbol sofort widerrufen. Pro Konto sind bis zu 25 aktive Tokens gleichzeitig möglich.

2. Eine Anfrage senden

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. Die Antwort prüfen

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

Authentifizierung

Jede Anfrage an /api/v1/ muss einen Authorization-Header mitschicken. Zwei Token-Typen werden akzeptiert:

• Personal Access Token (PAT) — langlebiger Bearer-Token, den du im Dashboard unter Einstellungen → API-Zugriff erstellst. Format: lgpat_ + 64 Hex-Zeichen. Auf Scopes begrenzt, widerrufbar, optional mit Ablaufdatum. Für alle Integrationen von Drittanbietern empfohlen.
• Session-JWT — kurzlebiger Token, der an die eigenen Apps (iOS, Dashboard) ausgegeben wird. Ohne Scope-Beschränkungen. Für einmalige Tests kannst du ihn verwenden, wenn du ihn aus einer angemeldeten Sitzung extrahieren kannst — der unterstützte Weg sind aber PATs.

Header-Format

Authorization: Bearer lgpat_a1b2c3d4e5f6…

Token-Limits

• Bis zu 25 aktive PATs pro Manilo-Konto.
• Beim Erstellen kann optional ein Ablaufdatum gesetzt werden. Abgelaufene Tokens liefern 401 Unauthorized.
• Widerrufene Tokens funktionieren sofort nicht mehr — Manilo speichert nur einen SHA-256-Hash des Tokens, nie den Wert selbst. Ein geleakter Token lässt sich daher nicht wiederherstellen, sondern nur widerrufen und ersetzen.

Häufige Auth-Fehler

401

Token fehlt, ist fehlerhaft, abgelaufen oder widerrufen.

403

Der Token ist gültig, aber der angefragte Endpunkt erfordert einen Scope, den dein PAT nicht hat — oder dein Cloud-Abo ist nicht aktiv.

Scopes

PATs folgen einem Deny-by-default-Modell. Ein Token darf nur Endpunkte aufrufen, deren erforderlichen Scope er besitzt; alles andere liefert 403 Forbidden. Vergib immer nur die Scopes, die deine Integration wirklich braucht.

Verfügbare Scopes:

Jeder unten aufgeführte Endpunkt zeigt seinen erforderlichen Scope als kleinen lila Chip. :write-Scopes schließen :read nicht ein — fordere beide an, wenn du beide brauchst.

Abo-Pflicht

Alle v1-Endpunkte — auch die rein lesenden — setzen voraus, dass die aufrufende Person ein aktives Manilo-Cloud-Abo hat. Ist das Abo gekündigt, abgelaufen oder nie gestartet worden, antwortet die API mit:

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

Über den Header X-Subscription-Required können Clients eine Abo-Sperre von einer allgemeinen Rechteverweigerung unterscheiden. Du stellst den Zugriff wieder her, indem du Cloud in der iOS-App oder unter dashboard.manilo.app/upgrade reaktivierst.

Fehler

Fehler nutzen die üblichen HTTP-Statuscodes. Der Response-Body ist ein JSON-Objekt mit einem einzigen Feld:

{ "error": "Human-readable message" }

Statuscodes, die du behandeln solltest:

200

OK — Ressource oder Liste zurückgegeben.

201

Created — neue Ressource angelegt. Der Header Location verweist auf die kanonische URL.

204

No Content — Löschen erfolgreich; kein Body.

400

Validierung fehlgeschlagen — Pflichtfeld fehlt, Wert außerhalb des zulässigen Bereichs, fehlerhaftes JSON.

401

Authentifizierung fehlgeschlagen — siehe Authentifizierung.

403

Zugriff verweigert — unzureichender Scope oder inaktives Abo.

404

Ressource nicht gefunden oder durch Berechtigungen verborgen.

409

Konflikt — z. B. Verletzung einer Eindeutigkeitsbedingung.

5xx

Serverseitiger Fehler. Idempotente Lesezugriffe können mit exponentiellem Backoff sicher wiederholt werden.

Paginierung & Filter

List-Endpunkte geben standardmäßig alle passenden Einträge zurück. Transaktionen — die einzige Ressource, die stark wachsen kann — unterstützen Cursor-basierte Paginierung.

Transaktions-Cursor

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

Die Antwort enthält ein Feld nextCursor. Gib es als Query-Parameter cursor zurück, um die nächste Seite zu laden; wenn nextCursor den Wert null hat, ist das Ende erreicht.

• limit — Seitengröße, begrenzt auf 1..200. Standard 50.
• cursor — opaker Token. Behandle ihn als Blackbox.
• type, dateFrom, dateTo, categoryId, accountId, groupId — optionale Filter; siehe den Endpunkt Transaktionen auflisten.

Typen & Formate

• IDs — opake Strings. Parse sie nicht; behandle sie als UTF-8-Bezeichner mit Beachtung der Groß- und Kleinschreibung.
• Zeitstempel — ISO-8601 in UTC mit abschließendem Z, z. B. "2026-05-13T10:30:00Z".
• Datumsangaben (z. B. das Feld date einer Transaktion) — dasselbe ISO-8601-Format, relevant ist aber nur der Datumsteil.
• Beträge — JSON-Zahlen in Haupteinheiten mit bis zu 4 Nachkommastellen (z. B. 12.50). Nie in Untereinheiten. Immer zusammen mit currencyCode.
• Währungscodes — ISO-4217, genau drei Großbuchstaben (z. B. "EUR", "USD", "GBP").
• Löschvorgänge — alle Löschoperationen sind Soft-Deletes. Gelöschte Einträge erscheinen nicht mehr in List- und Get-Antworten; geteilte Zugriffe und bisherige Belege bleiben erhalten.
• Seiteneffekte — das Löschen eines Kontos, einer Kategorie oder einer Gruppe lässt abhängige Transaktionen unberührt; ihre Verweise werden gelöst. Der Endpunkt Konto löschen akzeptiert eine ausdrückliche Strategie.

Konten

Konten sind die Behälter, die Salden halten — ein Bankkonto, eine Kreditkarte, ein Bargeldkonto, ein Depot. Jede Transaktion ist mit einem Konto verknüpft (bei Umbuchungen mit zweien).

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

Kategorien

Kategorien beschreiben, wofür eine Transaktion da ist (Lebensmittel, Miete, Freelance-Einnahmen). Systemkategorien sind schreibgeschützt und für alle Nutzer identisch; deine eigenen Kategorien verwaltest du selbst. Kategoriegruppen bündeln verwandte Kategorien.

Eigene Kategorien

Kategoriegruppen

Budgets

Ein Budget begrenzt die Ausgaben für eine Kategorie (oder, wenn categoryId null ist, für das gesamte Haushaltsbuch) über einen wiederkehrenden Zeitraum. Teile ein Budget mit einer Gruppe, indem du groupId setzt.

Gruppen

Gruppen sind geteilte Haushaltsbücher — ein Haushalt, eine Reise, eine WG. Alle Mitglieder sehen dieselben Transaktionen; die Eigentümerschaft bleibt persönlich. Mitgliedschaften und Einladungen werden in der iOS-App verwaltet; hier bildet die API nur die Ressource selbst ab.

Transaktionen

Transaktionen sind die Verben des Haushaltsbuchs. Es gibt sie in vier Ausprägungen: income, expense, transfer (von Konto zu Konto) und adjustment (einmalige Korrektur). Der Basis-Endpunkt legt Einnahmen und Ausgaben an; Umbuchungen haben einen eigenen Endpunkt; für große Importmengen gibt es Bulk-Varianten.

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

Bulk-Operationen

Für Importer gedacht. Jeder Batch ist auf 100 Einträge begrenzt und läuft nach dem Prinzip Best Effort: Eine einzelne fehlerhafte Zeile setzt die übrigen nicht zurück. Erfolgreiche Einträge und Fehler je Zeile werden getrennt gemeldet, damit du die fehlgeschlagenen wiederholen kannst.

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

Das Transaktionsobjekt

Icons

Manilo bringt einen kuratierten Icon-Satz und eine Farbpalette mit, die überall verwendet werden — für Konten, Kategorien und Gruppen. Lade den Katalog einmal, cache ihn und verwende die Bezeichner beim Anlegen von Ressourcen wieder.

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

Versionierung

• Keine Breaking Changes innerhalb von v1. Wir ergänzen ausschließlich neue Endpunkte, neue optionale Felder und neue Enum-Werte. Typ, Nullbarkeit oder Pflichtstatus eines Feldes ändern sich nicht.
• Neue Enum-Werte sind kein Breaking Change. Behandle unbekannte Werte von type, source oder action als „nicht anzeigen“, statt abzustürzen — wir ergänzen sie, wenn das Produkt wächst.
• Datumsversionierte Breaking Changes (falls je nötig) erscheinen unter /api/v2/ mit mindestens 6 Monaten Parallelbetrieb und einem Deprecation-Header in den v1-Antworten.

Support

Bug gefunden, einen Endpunkt vermisst oder etwas Undokumentiertes entdeckt? Öffne das Hilfe-Center oder schreib an support@manilo.app — bitte gib beim Melden eines Problems die Request-ID an (sie wird im Response-Header X-Request-Id zurückgegeben).

Für sicherheitsrelevante Meldungen (ein geleakter Token, eine umgangene Berechtigung, ein unbefugter Lesezugriff) schreib an security@manilo.app.