---
name: finanz-api
description: Referenz aller REST-Endpunkte des Finanzberatungs-Tools (Konten, Buchungen, Kategorien, Regeln, Importe, wiederkehrende/geplante Posten, Kredite, Szenarien) mit curl-Beispielen. Use when Claude Code Daten aus dem Finanzberatungs-Tool lesen oder schreiben soll — Konten/Salden abfragen, Buchungen filtern/anlegen/korrigieren, Importe verwalten, Planungsposten oder Szenarien anlegen und durchrechnen.
---

# Finanz-API

REST/JSON unter `http://127.0.0.1:8096/api/…`, vollständig dokumentiert unter
`http://127.0.0.1:8096/docs` (OpenAPI/Swagger). Alle Endpunkte erfordern den
Header `Authorization: Bearer <FB_API_KEY>`.

## Key extrahieren

```bash
KEY=$(grep '^FB_API_KEY=' $HOME/.local/share/finance_pod/.env | cut -d= -f2 | tr -d "'")
```

Verwende `$KEY` in allen folgenden Beispielen. Den Key niemals ausgeben,
loggen oder in Antworten an den Nutzer wiederholen.

## Konten (`/api/accounts`)

`GET` (Liste inkl. aktuellem Saldo je Konto), `GET /{id}`, `POST` (Konto
anlegen: `bank`, `iban`, `name`, `type`).

```bash
curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/accounts | jq
```

## Buchungen (`/api/transactions`)

`GET` mit Filtern `account_id`, `date_from`, `date_to`, `category_id`, `q`
(Volltext auf Verwendungszweck/Gegenpartei), `status` (Default `confirmed`),
`limit`/`offset`. `POST` legt eine Buchung manuell an (`force: true`
überschreibt die Duplikat-Prüfung). `PATCH /{id}` ändert **nur**
`category_id` — echte Buchungen sonst nie verändern.

```bash
curl -s -H "Authorization: Bearer $KEY" \
  "http://127.0.0.1:8096/api/transactions?date_from=2026-01-01&category_id=3&limit=50" | jq
```

## Kategorien (`/api/categories`)

`GET`/`POST` (`name`).

```bash
curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/categories | jq

curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Energie"}' \
  http://127.0.0.1:8096/api/categories | jq
```

## Kategorie-Regeln (`/api/category-rules`)

`GET`/`POST` (`pattern`, `category_id`, `priority`) und
`DELETE /api/category-rules/{id}`. Regeln kategorisieren künftige Importe
automatisch.

```bash
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"pattern": "REWE", "category_id": 3, "priority": 50}' \
  http://127.0.0.1:8096/api/category-rules | jq
```

## Importe (`/api/imports`)

`POST /upload` (multipart, PDF), `POST /scan-inbox` (scannt die Inbox neu),
`GET` (Liste mit Status `draft`/`confirmed`/`error`), `GET /{id}/preview`
(Buchungen + Saldo-Check + Duplikat-Zahl), `POST /{id}/confirm`
(übernimmt die Vorschau endgültig), `DELETE /{id}`.

```bash
curl -s -X POST -H "Authorization: Bearer $KEY" \
  http://127.0.0.1:8096/api/imports/scan-inbox | jq
```

## Wiederkehrende Posten (`/api/recurring`)

`GET`/`POST` (`name`, `amount`, `rhythm`, `due_day`, `start_date`,
`end_date`, `category_id`), `PATCH`/`DELETE /{id}`, sowie
`GET /recurring/suggestions` (Muster-Erkennung aus importierten Buchungen).

```bash
curl -s -H "Authorization: Bearer $KEY" \
  http://127.0.0.1:8096/api/recurring/suggestions | jq
```

## Geplante Einmalposten (`/api/planned`)

`GET`/`POST` (`name`, `amount`, `due`, `category_id`), `PATCH`/`DELETE /{id}`.

```bash
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Zahnarzt", "amount": -450.00, "due": "2026-09-01"}' \
  http://127.0.0.1:8096/api/planned | jq
```

## Kredite (`/api/loans`)

`GET`/`POST` (`name`, `principal`, `annual_rate_pct`, `term_months`,
`payout_date`, `repayment_type`: `annuity`|`bullet`), `PATCH`/`DELETE /{id}`,
`GET /{id}/schedule` (Tilgungsplan: Rate, Zins, Tilgung, Restschuld je Termin).

```bash
curl -s -H "Authorization: Bearer $KEY" \
  http://127.0.0.1:8096/api/loans/1/schedule | jq
```

## Szenarien (`/api/scenarios`)

`GET`/`POST` (`name`, `description`, `include_recurring`, `include_planned`),
`PATCH`/`DELETE /{id}`. Kredit zuordnen: `POST`/`DELETE
/{id}/loans/{loan_id}`. Modifikator hinzufügen: `POST /{id}/modifiers` mit
`target_type` (`category`|`recurring`), `target_id`, `kind`
(`percent`|`absolute`|`remove`), `value`; löschen über `DELETE
/{id}/modifiers/{mod_id}`.

```bash
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Basis-Szenario"}' \
  http://127.0.0.1:8096/api/scenarios | jq
```

## Durchrechnen (`/api/scenarios/{id}/project`)

`POST`, optionale Query-Parameter `horizon_days` und `start_date`. Antwort:
`low_point_date`, `low_point_balance`, `below_zero_date`,
`below_threshold_date`, `series` (Tagesreihe Datum/Saldo).

```bash
curl -s -X POST -H "Authorization: Bearer $KEY" \
  "http://127.0.0.1:8096/api/scenarios/1/project?horizon_days=180" | jq
```