{"openapi":"3.1.0","externalDocs":{"description":"Public API methodology","url":"https://investboard.com/calculators/api/methodology"},"info":{"title":"Investboard Public Calculator API","version":"2026-10-15.2","description":"Anonymous, stateless German financial models. EUR amounts; input rates in percentage points. POST JSON only. 60 units per IP per minute (one per comparison scenario), best-effort during limiter outages. No account data is read or saved."},"servers":[{"url":"https://investboard.com"}],"components":{"schemas":{},"parameters":{}},"paths":{"/api/v1/public/calculators/abgeltungssteuer":{"get":{"operationId":"describeAbgeltungssteuer","summary":"Input schema: Capital Gains Tax Calculator (Germany)","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateAbgeltungssteuer","summary":"Capital Gains Tax Calculator (Germany)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"kapitalertrag":{"type":"number","minimum":0,"maximum":100000000,"default":5000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"ertragsart":{"type":"string","enum":["general","aktienverkauf","dividende","etf"],"default":"general"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"kapitalertrag":5000,"ertragsart":"general","taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["abgeltungssteuer"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"kapitalertrag":{"type":"number","minimum":0,"maximum":100000000,"default":5000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"ertragsart":{"type":"string","enum":["general","aktienverkauf","dividende","etf"],"default":"general"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"brutto_ertrag":{"type":"number","description":"EUR, not cents."},"fsa_offset":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_ertrag":{"type":"number","description":"EUR, not cents."},"kapitalertragsteuer":{"type":"number","description":"EUR, not cents."},"solidaritaetszuschlag":{"type":"number","description":"EUR, not cents."},"kirchensteuer":{"type":"number","description":"EUR, not cents."},"gesamte_steuer":{"type":"number","description":"EUR, not cents."},"effektiver_steuersatz":{"type":"number","description":"Fraction: 0.25 means 25%."},"netto_ertrag":{"type":"number","description":"EUR, not cents."},"kirchensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"teilfreistellung_betrag":{"type":"number","description":"EUR, not cents."}},"required":["brutto_ertrag","fsa_offset","steuerpflichtiger_ertrag","kapitalertragsteuer","solidaritaetszuschlag","kirchensteuer","gesamte_steuer","effektiver_steuersatz","netto_ertrag","kirchensteuer_rate","teilfreistellung_betrag"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/netto-dividende":{"get":{"operationId":"describeNettoDividende","summary":"Input schema: Net Dividend Calculator (Germany)","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateNettoDividende","summary":"Net Dividend Calculator (Germany)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"brutto_dividende":{"type":"number","minimum":0,"maximum":100000000,"default":500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"quelle":{"type":"string","enum":["aktie","etf_aktien","mischfonds"],"default":"aktie"},"isin":{"type":"string","pattern":"^[A-Z]{2}[A-Z0-9]{9}[0-9]$","description":"Optional issuer ISIN used for country-level withholding assumptions; not a live security lookup."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"brutto_dividende":500,"quelle":"aktie","taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["netto-dividende"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"brutto_dividende":{"type":"number","minimum":0,"maximum":100000000,"default":500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"quelle":{"type":"string","enum":["aktie","etf_aktien","mischfonds"],"default":"aktie"},"isin":{"type":"string","pattern":"^[A-Z]{2}[A-Z0-9]{9}[0-9]$","description":"Optional issuer ISIN used for country-level withholding assumptions; not a live security lookup."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"brutto_dividende":{"type":"number","description":"EUR, not cents."},"teilfreistellung_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"teilfreistellung_betrag":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_betrag":{"type":"number","description":"EUR, not cents."},"steuer":{"type":"object","properties":{"brutto_ertrag":{"type":"number","description":"EUR, not cents."},"fsa_offset":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_ertrag":{"type":"number","description":"EUR, not cents."},"kapitalertragsteuer":{"type":"number","description":"EUR, not cents."},"solidaritaetszuschlag":{"type":"number","description":"EUR, not cents."},"kirchensteuer":{"type":"number","description":"EUR, not cents."},"gesamte_steuer":{"type":"number","description":"EUR, not cents."},"effektiver_steuersatz":{"type":"number","description":"Fraction: 0.25 means 25%."},"netto_ertrag":{"type":"number","description":"EUR, not cents."},"kirchensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."}},"required":["brutto_ertrag","fsa_offset","steuerpflichtiger_ertrag","kapitalertragsteuer","solidaritaetszuschlag","kirchensteuer","gesamte_steuer","effektiver_steuersatz","netto_ertrag","kirchensteuer_rate"],"additionalProperties":false},"quellensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"quellensteuer_betrag":{"type":"number","description":"EUR, not cents."},"anrechenbare_quellensteuer":{"type":"number","description":"EUR, not cents."},"erstattungsfaehige_quellensteuer":{"type":"number","description":"EUR, not cents."},"deutsche_reststeuer":{"type":"number","description":"EUR, not cents."},"quellensteuer_status":{"type":"string","enum":["credited","fund_level","none","unavailable"],"description":"unavailable means withholding was omitted because country assumptions are unavailable; none means no modeled investor withholding."},"netto_dividende":{"type":"number","description":"EUR, not cents."}},"required":["brutto_dividende","teilfreistellung_rate","teilfreistellung_betrag","steuerpflichtiger_betrag","steuer","quellensteuer_rate","quellensteuer_betrag","anrechenbare_quellensteuer","erstattungsfaehige_quellensteuer","deutsche_reststeuer","quellensteuer_status","netto_dividende"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/vorabpauschale":{"get":{"operationId":"describeVorabpauschale","summary":"Input schema: Vorabpauschale Calculator 2026 (Advance Lump Sum Tax)","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateVorabpauschale","summary":"Vorabpauschale Calculator 2026 (Advance Lump Sum Tax)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"wert_jahresanfang":{"type":"number","minimum":0,"maximum":100000000,"default":10000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"wert_jahresende":{"type":"number","minimum":0,"maximum":100000000,"default":11500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"ausschuettungen":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","IMMOBILIENFONDS","IMMOBILIENFONDS_AUSLAND","SONSTIGE"],"default":"AKTIENFONDS"},"steuerjahr":{"anyOf":[{"type":"number","enum":[2023]},{"type":"number","enum":[2024]},{"type":"number","enum":[2025]},{"type":"number","enum":[2026]}],"default":2025,"description":"Only years with published Basiszins in the model are accepted. Single-position, full-year holding."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"wert_jahresanfang":10000,"wert_jahresende":11500,"ausschuettungen":0,"fondstyp":"AKTIENFONDS","steuerjahr":2025,"taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["vorabpauschale"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"wert_jahresanfang":{"type":"number","minimum":0,"maximum":100000000,"default":10000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"wert_jahresende":{"type":"number","minimum":0,"maximum":100000000,"default":11500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"ausschuettungen":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","IMMOBILIENFONDS","IMMOBILIENFONDS_AUSLAND","SONSTIGE"],"default":"AKTIENFONDS"},"steuerjahr":{"anyOf":[{"type":"number","enum":[2023]},{"type":"number","enum":[2024]},{"type":"number","enum":[2025]},{"type":"number","enum":[2026]}],"default":2025,"description":"Only years with published Basiszins in the model are accepted. Single-position, full-year holding."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"basiszins":{"type":"number","description":"Percentage points: 4 means 4%."},"basisertrag":{"type":"number","description":"EUR, not cents."},"wertsteigerung":{"type":"number","description":"EUR, not cents."},"vorabpauschale_brutto":{"type":"number","description":"EUR, not cents."},"teilfreistellung_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"teilfreistellung_betrag":{"type":"number","description":"EUR, not cents."},"vorabpauschale_steuerpflichtig":{"type":"number","description":"EUR, not cents."},"steuer":{"type":"object","properties":{"brutto_ertrag":{"type":"number","description":"EUR, not cents."},"fsa_offset":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_ertrag":{"type":"number","description":"EUR, not cents."},"kapitalertragsteuer":{"type":"number","description":"EUR, not cents."},"solidaritaetszuschlag":{"type":"number","description":"EUR, not cents."},"kirchensteuer":{"type":"number","description":"EUR, not cents."},"gesamte_steuer":{"type":"number","description":"EUR, not cents."},"effektiver_steuersatz":{"type":"number","description":"Fraction: 0.25 means 25%."},"netto_ertrag":{"type":"number","description":"EUR, not cents."},"kirchensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."}},"required":["brutto_ertrag","fsa_offset","steuerpflichtiger_ertrag","kapitalertragsteuer","solidaritaetszuschlag","kirchensteuer","gesamte_steuer","effektiver_steuersatz","netto_ertrag","kirchensteuer_rate"],"additionalProperties":false}},"required":["basiszins","basisertrag","wertsteigerung","vorabpauschale_brutto","teilfreistellung_rate","teilfreistellung_betrag","vorabpauschale_steuerpflichtig","steuer"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/thesaurierer-vs-ausschuetter":{"get":{"operationId":"describeThesauriererVsAusschuetter","summary":"Input schema: Accumulating vs. Distributing Fund Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateThesauriererVsAusschuetter","summary":"Accumulating vs. Distributing Fund Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"initial_investment":{"type":"number","minimum":0,"maximum":100000000,"default":10000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthly_contribution":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annual_return":{"type":"number","minimum":1,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"distribution_yield":{"type":"number","minimum":0,"maximum":6,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"years":{"type":"integer","minimum":1,"maximum":40,"default":20},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","SONSTIGE"],"default":"AKTIENFONDS"},"reinvest_distributions":{"type":"boolean","default":true},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"initial_investment":10000,"monthly_contribution":300,"annual_return":7,"distribution_yield":2,"years":20,"fondstyp":"AKTIENFONDS","reinvest_distributions":true,"taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["thesaurierer-vs-ausschuetter"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"initial_investment":{"type":"number","minimum":0,"maximum":100000000,"default":10000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthly_contribution":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annual_return":{"type":"number","minimum":1,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"distribution_yield":{"type":"number","minimum":0,"maximum":6,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"years":{"type":"integer","minimum":1,"maximum":40,"default":20},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","SONSTIGE"],"default":"AKTIENFONDS"},"reinvest_distributions":{"type":"boolean","default":true},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearly_data":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"thesaurierer_value":{"type":"number","description":"EUR, not cents."},"thesaurierer_vorabpauschale_tax":{"type":"number","description":"EUR, not cents."},"ausschuetter_value":{"type":"number","description":"EUR, not cents."},"ausschuetter_distribution_tax":{"type":"number","description":"EUR, not cents."},"ausschuetter_distributions_gross":{"type":"number","description":"EUR, not cents."},"ausschuetter_distributions_net":{"type":"number","description":"EUR, not cents."}},"required":["year","thesaurierer_value","thesaurierer_vorabpauschale_tax","ausschuetter_value","ausschuetter_distribution_tax","ausschuetter_distributions_gross","ausschuetter_distributions_net"],"additionalProperties":false}},"thesaurierer_final":{"type":"number","description":"EUR, not cents."},"ausschuetter_final":{"type":"number","description":"EUR, not cents."},"thesaurierer_advantage_eur":{"type":"number","description":"EUR, not cents."},"thesaurierer_advantage_pct":{"type":"number","description":"Percentage points: 4 means 4%."},"thesaurierer_total_taxes":{"type":"number","description":"EUR, not cents."},"ausschuetter_total_taxes":{"type":"number","description":"EUR, not cents."},"total_contributions":{"type":"number","description":"EUR, not cents."}},"required":["yearly_data","thesaurierer_final","ausschuetter_final","thesaurierer_advantage_eur","thesaurierer_advantage_pct","thesaurierer_total_taxes","ausschuetter_total_taxes","total_contributions"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/freistellungsauftrag":{"get":{"operationId":"describeFreistellungsauftrag","summary":"Input schema: Freistellungsauftrag Optimizer (Tax Exemption Order)","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateFreistellungsauftrag","summary":"Freistellungsauftrag Optimizer (Tax Exemption Order)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"brokers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"zinsen":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"dividenden":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"vorabpauschale":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"realisierte_gewinne":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"current_fsa":{"type":"number","minimum":0,"maximum":2000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."}},"required":["name"],"additionalProperties":false},"minItems":1,"maxItems":6,"default":[{"name":"Broker 1","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0},{"name":"Broker 2","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0}]},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"brokers":[{"name":"Broker 1","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0},{"name":"Broker 2","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0}],"taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["freistellungsauftrag"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"brokers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"zinsen":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"dividenden":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"vorabpauschale":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"realisierte_gewinne":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"current_fsa":{"type":"number","minimum":0,"maximum":2000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."}},"required":["name"],"additionalProperties":false},"minItems":1,"maxItems":6,"default":[{"name":"Broker 1","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0},{"name":"Broker 2","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0}]},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"brokers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"expected_income":{"type":"number","description":"EUR, not cents."},"current_fsa":{"type":"number","description":"EUR, not cents."},"optimal_fsa":{"type":"number","description":"EUR, not cents."},"tax_with_current":{"type":"number","description":"EUR, not cents."},"tax_with_optimal":{"type":"number","description":"EUR, not cents."},"delta":{"type":"number","description":"EUR, not cents."}},"required":["name","expected_income","current_fsa","optimal_fsa","tax_with_current","tax_with_optimal","delta"],"additionalProperties":false}},"total_expected_income":{"type":"number","description":"EUR, not cents."},"total_fsa_available":{"type":"number","description":"EUR, not cents."},"total_fsa_optimal":{"type":"number","description":"EUR, not cents."},"total_tax_current":{"type":"number","description":"EUR, not cents."},"total_tax_optimal":{"type":"number","description":"EUR, not cents."},"savings":{"type":"number","description":"EUR, not cents."},"warnings":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["over_limit","under_utilised","january_risk"]},"message":{"type":"string"}},"required":["type","message"],"additionalProperties":false}}},"required":["brokers","total_expected_income","total_fsa_available","total_fsa_optimal","total_tax_current","total_tax_optimal","savings","warnings"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/etf-sparplan":{"get":{"operationId":"describeEtfSparplan","summary":"Input schema: ETF Savings Plan Calculator (Germany)","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateEtfSparplan","summary":"ETF Savings Plan Calculator (Germany)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"initial_investment":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthly_rate":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annual_increase":{"type":"number","minimum":0,"maximum":10,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"annual_return":{"type":"number","minimum":1,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"years":{"type":"integer","minimum":1,"maximum":40,"default":20},"include_tax_drag":{"type":"boolean","default":false},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","SONSTIGE"],"default":"AKTIENFONDS"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"initial_investment":0,"monthly_rate":300,"annual_increase":2,"annual_return":7,"years":20,"include_tax_drag":false,"fondstyp":"AKTIENFONDS","taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["etf-sparplan"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"initial_investment":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthly_rate":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annual_increase":{"type":"number","minimum":0,"maximum":10,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"annual_return":{"type":"number","minimum":1,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"years":{"type":"integer","minimum":1,"maximum":40,"default":20},"include_tax_drag":{"type":"boolean","default":false},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","SONSTIGE"],"default":"AKTIENFONDS"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearly_data":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"contributions_cumulative":{"type":"number","description":"EUR, not cents."},"value_before_tax":{"type":"number","description":"EUR, not cents."},"value_after_tax":{"type":"number","description":"EUR, not cents."},"annual_contribution":{"type":"number","description":"EUR, not cents."},"vorabpauschale_tax":{"type":"number","description":"EUR, not cents."}},"required":["year","contributions_cumulative","value_before_tax","value_after_tax","annual_contribution","vorabpauschale_tax"],"additionalProperties":false}},"final_value":{"type":"number","description":"EUR, not cents."},"total_contributions":{"type":"number","description":"EUR, not cents."},"total_growth":{"type":"number","description":"EUR, not cents."},"total_taxes_paid":{"type":"number","description":"EUR, not cents."},"final_value_no_tax":{"type":"number","description":"EUR, not cents."},"tax_drag_eur":{"type":"number","description":"EUR, not cents."},"tax_drag_pct":{"type":"number","description":"Percentage points: 4 means 4%."}},"required":["yearly_data","final_value","total_contributions","total_growth","total_taxes_paid","final_value_no_tax","tax_drag_eur","tax_drag_pct"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/notgroschen":{"get":{"operationId":"describeNotgroschen","summary":"Input schema: Emergency Fund Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateNotgroschen","summary":"Emergency Fund Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"monthlyExpenses":{"type":"number","minimum":1,"maximum":100000000,"default":2500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"bufferMonths":{"anyOf":[{"type":"number","enum":[3]},{"type":"number","enum":[6]},{"type":"number","enum":[9]},{"type":"number","enum":[12]}],"default":6},"currentSavings":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlySavingsCapacity":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"parkingVehicle":{"type":"string","enum":["tagesgeld","geldmarkt_etf","festgeld_leiter"],"default":"tagesgeld"}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"monthlyExpenses":2500,"bufferMonths":6,"currentSavings":0,"monthlySavingsCapacity":300,"parkingVehicle":"tagesgeld"},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["notgroschen"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"monthlyExpenses":{"type":"number","minimum":1,"maximum":100000000,"default":2500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"bufferMonths":{"anyOf":[{"type":"number","enum":[3]},{"type":"number","enum":[6]},{"type":"number","enum":[9]},{"type":"number","enum":[12]}],"default":6},"currentSavings":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlySavingsCapacity":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"parkingVehicle":{"type":"string","enum":["tagesgeld","geldmarkt_etf","festgeld_leiter"],"default":"tagesgeld"}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"targetAmount":{"type":"number","description":"EUR, not cents."},"deficit":{"type":"number","description":"EUR, not cents."},"monthsToTarget":{"type":"integer","minimum":0,"description":"Months to target, capped at 600; zero with a positive deficit and no saving capacity does not mean funded."},"targetUnreachable":{"type":"boolean","description":"The 600-month horizon was exhausted. Also inspect deficit and saving capacity when monthsToTarget is zero."},"targetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC modeled target date; only meaningful if the target is funded or reachable with positive saving capacity."},"expectedReturn":{"type":"number","description":"EUR, not cents."},"recommendedVehicle":{"type":"string","enum":["tagesgeld","geldmarkt_etf","festgeld_leiter"]}},"required":["targetAmount","deficit","monthsToTarget","targetUnreachable","targetDate","expectedReturn","recommendedVehicle"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/eigenkapital":{"get":{"operationId":"describeEigenkapital","summary":"Input schema: Home Equity Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateEigenkapital","summary":"Home Equity Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"purchasePrice":{"type":"number","minimum":0,"maximum":100000000,"default":350000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"bundesland":{"type":"string","enum":["baden-wuerttemberg","bayern","berlin","brandenburg","bremen","hamburg","hessen","mecklenburg-vorpommern","niedersachsen","nordrhein-westfalen","rheinland-pfalz","saarland","sachsen","sachsen-anhalt","schleswig-holstein","thueringen"],"default":"nordrhein-westfalen"},"eigenkapitalQuote":{"type":"number","minimum":10,"maximum":40,"default":20,"description":"Equity percentage points, e.g. 20 for 20%."},"currentSavings":{"type":"number","minimum":0,"maximum":100000000,"default":30000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlySavingsCapacity":{"type":"number","minimum":0,"maximum":100000000,"default":500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"savingsReturnPct":{"type":"number","minimum":0,"maximum":8,"default":4,"description":"Annual percentage points: 6 means 6%, not 0.06."}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"purchasePrice":350000,"bundesland":"nordrhein-westfalen","eigenkapitalQuote":20,"currentSavings":30000,"monthlySavingsCapacity":500,"savingsReturnPct":4},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["eigenkapital"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"purchasePrice":{"type":"number","minimum":0,"maximum":100000000,"default":350000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"bundesland":{"type":"string","enum":["baden-wuerttemberg","bayern","berlin","brandenburg","bremen","hamburg","hessen","mecklenburg-vorpommern","niedersachsen","nordrhein-westfalen","rheinland-pfalz","saarland","sachsen","sachsen-anhalt","schleswig-holstein","thueringen"],"default":"nordrhein-westfalen"},"eigenkapitalQuote":{"type":"number","minimum":10,"maximum":40,"default":20,"description":"Equity percentage points, e.g. 20 for 20%."},"currentSavings":{"type":"number","minimum":0,"maximum":100000000,"default":30000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlySavingsCapacity":{"type":"number","minimum":0,"maximum":100000000,"default":500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"savingsReturnPct":{"type":"number","minimum":0,"maximum":8,"default":4,"description":"Annual percentage points: 6 means 6%, not 0.06."}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"nebenkostenTotal":{"type":"number","description":"EUR, not cents."},"nebenkostenBreakdown":{"type":"object","properties":{"grunderwerbsteuer":{"type":"number","description":"EUR, not cents."},"notarGrundbuch":{"type":"number","description":"EUR, not cents."},"makler":{"type":"number","description":"EUR, not cents."}},"required":["grunderwerbsteuer","notarGrundbuch","makler"],"additionalProperties":false},"eigenkapitalRequired":{"type":"number","description":"EUR, not cents."},"totalUpfront":{"type":"number","description":"EUR, not cents."},"deficit":{"type":"number","description":"EUR, not cents."},"monthsToTarget":{"type":"integer","minimum":0,"description":"Months to target, capped at 600; zero with a positive deficit and no saving capacity does not mean funded."},"targetUnreachable":{"type":"boolean","description":"The 600-month horizon was exhausted. Also inspect deficit and saving capacity when monthsToTarget is zero."},"targetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC modeled target date; only meaningful if the target is funded or reachable with positive saving capacity."},"monthlyMortgageEstimate":{"type":"number","description":"EUR, not cents."}},"required":["nebenkostenTotal","nebenkostenBreakdown","eigenkapitalRequired","totalUpfront","deficit","monthsToTarget","targetUnreachable","targetDate","monthlyMortgageEstimate"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/rentenluecke":{"get":{"operationId":"describeRentenluecke","summary":"Input schema: Pension Gap Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateRentenluecke","summary":"Pension Gap Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"currentAge":{"type":"integer","minimum":18,"maximum":65,"default":35},"retirementAge":{"type":"integer","minimum":55,"maximum":70,"default":67},"grossMonthlyIncome":{"type":"number","minimum":0,"maximum":100000000,"default":4000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"workingYearsSoFar":{"type":"integer","minimum":0,"maximum":50,"default":10},"desiredRetirementIncome":{"type":"number","minimum":0,"maximum":100000000,"default":2500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"existingPrivateProvision":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":6,"description":"Annual percentage points: 6 means 6%, not 0.06."}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"currentAge":35,"retirementAge":67,"grossMonthlyIncome":4000,"workingYearsSoFar":10,"desiredRetirementIncome":2500,"existingPrivateProvision":0,"monthlyContribution":300,"annualReturnPct":6},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["rentenluecke"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"currentAge":{"type":"integer","minimum":18,"maximum":65,"default":35},"retirementAge":{"type":"integer","minimum":55,"maximum":70,"default":67},"grossMonthlyIncome":{"type":"number","minimum":0,"maximum":100000000,"default":4000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"workingYearsSoFar":{"type":"integer","minimum":0,"maximum":50,"default":10},"desiredRetirementIncome":{"type":"number","minimum":0,"maximum":100000000,"default":2500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"existingPrivateProvision":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":6,"description":"Annual percentage points: 6 means 6%, not 0.06."}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"estimatedStatePension":{"type":"number","description":"Estimated monthly state pension, EUR."},"monthlyGap":{"type":"number","description":"EUR, not cents."},"annualGap":{"type":"number","description":"EUR, not cents."},"capitalNeeded":{"type":"number","description":"EUR, not cents."},"capitalNeededAfterExisting":{"type":"number","description":"EUR, not cents."},"monthlySavingsNeeded":{"type":"number","description":"EUR, not cents."},"surplusOrDeficit":{"type":"number","description":"EUR, not cents."},"yearsUntilRetirement":{"type":"number","description":"Elapsed years, possibly fractional."}},"required":["estimatedStatePension","monthlyGap","annualGap","capitalNeeded","capitalNeededAfterExisting","monthlySavingsNeeded","surplusOrDeficit","yearsUntilRetirement"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/entnahmeplan":{"get":{"operationId":"describeEntnahmeplan","summary":"Input schema: Withdrawal Plan Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateEntnahmeplan","summary":"Withdrawal Plan Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"portfolioValue":{"type":"number","minimum":0,"maximum":100000000,"default":500000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyWithdrawal":{"type":"number","minimum":0,"maximum":100000000,"default":2000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":5,"description":"Annual percentage points: 6 means 6%, not 0.06."},"inflationPct":{"type":"number","minimum":0,"maximum":5,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"strategy":{"type":"string","enum":["constant_nominal","constant_real","percentage"],"default":"constant_nominal"},"percentageRate":{"type":"number","minimum":0.1,"maximum":20,"default":4,"description":"Annual withdrawal percentage points: 4 means 4%."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"portfolioValue":500000,"monthlyWithdrawal":2000,"annualReturnPct":5,"inflationPct":2,"strategy":"constant_nominal","percentageRate":4,"taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["entnahmeplan"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"portfolioValue":{"type":"number","minimum":0,"maximum":100000000,"default":500000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyWithdrawal":{"type":"number","minimum":0,"maximum":100000000,"default":2000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":5,"description":"Annual percentage points: 6 means 6%, not 0.06."},"inflationPct":{"type":"number","minimum":0,"maximum":5,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"strategy":{"type":"string","enum":["constant_nominal","constant_real","percentage"],"default":"constant_nominal"},"percentageRate":{"type":"number","minimum":0.1,"maximum":20,"default":4,"description":"Annual withdrawal percentage points: 4 means 4%."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearlyData":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"balanceStart":{"type":"number","description":"EUR, not cents."},"withdrawal":{"type":"number","description":"EUR, not cents."},"grossWithdrawal":{"type":"number","description":"EUR, not cents."},"taxPaid":{"type":"number","description":"EUR, not cents."},"growth":{"type":"number","description":"EUR, not cents."},"balanceEnd":{"type":"number","description":"EUR, not cents."}},"required":["year","balanceStart","withdrawal","grossWithdrawal","taxPaid","growth","balanceEnd"],"additionalProperties":false}},"yearsUntilDepletion":{"type":["number","null"],"description":"Null means no depletion within the modeled horizon; it does not show that the withdrawals last for life."},"totalWithdrawals":{"type":"number","description":"EUR, not cents."},"totalTaxPaid":{"type":"number","description":"EUR, not cents."},"effectiveWithdrawalRate":{"type":"number","description":"Percentage points: 4 means 4%."},"remainingAt80":{"type":["number","null"],"description":"EUR at age 80; null if that age is outside the modeled age/horizon."},"remainingAt90":{"type":["number","null"],"description":"EUR at age 90; null if that age is outside the modeled age/horizon."}},"required":["yearlyData","yearsUntilDepletion","totalWithdrawals","totalTaxPaid","effectiveWithdrawalRate","remainingAt80","remainingAt90"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/schenkungsteuer":{"get":{"operationId":"describeSchenkungsteuer","summary":"Input schema: Gift Tax Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateSchenkungsteuer","summary":"Gift Tax Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"relationship":{"type":"string","enum":["spouse","child","grandchild","sibling","other"],"default":"child"},"giftAmount":{"type":"number","minimum":0,"maximum":100000000,"default":100000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"previousGifts10y":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"numberOfDonors":{"type":"integer","minimum":1,"maximum":2,"default":1},"optimizeOverTime":{"type":"boolean","default":false},"totalToTransfer":{"type":"number","minimum":0,"maximum":10000000,"default":100000,"description":"Used only when optimizeOverTime is true. Prior gifts are not modeled by optimization."}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"relationship":"child","giftAmount":100000,"previousGifts10y":0,"numberOfDonors":1,"optimizeOverTime":false,"totalToTransfer":100000},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["schenkungsteuer"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"relationship":{"type":"string","enum":["spouse","child","grandchild","sibling","other"],"default":"child"},"giftAmount":{"type":"number","minimum":0,"maximum":100000000,"default":100000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"previousGifts10y":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"numberOfDonors":{"type":"integer","minimum":1,"maximum":2,"default":1},"optimizeOverTime":{"type":"boolean","default":false},"totalToTransfer":{"type":"number","minimum":0,"maximum":10000000,"default":100000,"description":"Used only when optimizeOverTime is true. Prior gifts are not modeled by optimization."}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"anyOf":[{"type":"object","properties":{"freibetrag":{"type":"number","description":"EUR, not cents."},"totalFreibetrag":{"type":"number","description":"EUR, not cents."},"taxableAmount":{"type":"number","description":"EUR, not cents."},"taxRate":{"type":"number","description":"Fraction: 0.25 means 25%."},"taxDue":{"type":"number","description":"EUR, not cents."},"netGiftAmount":{"type":"number","description":"EUR, not cents."},"steuerklasse":{"type":"string","enum":["I","II","III"]},"optimalSchedule":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"amount":{"type":"number","description":"EUR, not cents."},"taxFree":{"type":"boolean"},"taxDue":{"type":"number","description":"EUR, not cents."}},"required":["year","amount","taxFree","taxDue"],"additionalProperties":false}},"totalTaxSaved":{"type":"number","description":"EUR, not cents."},"yearsNeeded":{"type":"number","description":"Elapsed years, possibly fractional."}},"required":["freibetrag","totalFreibetrag","taxableAmount","taxRate","taxDue","netGiftAmount","steuerklasse","optimalSchedule","totalTaxSaved","yearsNeeded"],"additionalProperties":false},{"type":"object","properties":{"freibetrag":{"type":"number","description":"EUR, not cents."},"totalFreibetrag":{"type":"number","description":"EUR, not cents."},"taxableAmount":{"type":"number","description":"EUR, not cents."},"taxRate":{"type":"number","description":"Fraction: 0.25 means 25%."},"taxDue":{"type":"number","description":"EUR, not cents."},"netGiftAmount":{"type":"number","description":"EUR, not cents."},"steuerklasse":{"type":"string","enum":["I","II","III"]}},"required":["freibetrag","totalFreibetrag","taxableAmount","taxRate","taxDue","netGiftAmount","steuerklasse"],"additionalProperties":false}],"description":"Scheduling mode adds optimalSchedule, totalTaxSaved and yearsNeeded. Single-gift mode returns the base fields."},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/junior-depot":{"get":{"operationId":"describeJuniorDepot","summary":"Input schema: Junior Depot Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateJuniorDepot","summary":"Junior Depot Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"childAge":{"type":"integer","minimum":0,"maximum":17,"default":0},"targetAge":{"type":"integer","minimum":1,"maximum":30,"default":18},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":100,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"initialDeposit":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"useKindergeld":{"type":"boolean","default":false},"hasNVBescheinigung":{"type":"boolean","default":false},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"childAge":0,"targetAge":18,"monthlyContribution":100,"initialDeposit":0,"annualReturnPct":7,"useKindergeld":false,"hasNVBescheinigung":false,"taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["junior-depot"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"childAge":{"type":"integer","minimum":0,"maximum":17,"default":0},"targetAge":{"type":"integer","minimum":1,"maximum":30,"default":18},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":100,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"initialDeposit":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"useKindergeld":{"type":"boolean","default":false},"hasNVBescheinigung":{"type":"boolean","default":false},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearlyData":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"age":{"type":"integer","description":"Child age in years."},"contributionsCumulative":{"type":"number","description":"EUR, not cents."},"valueGross":{"type":"number","description":"EUR, not cents."},"vorabpauschaleTax":{"type":"number","description":"EUR, not cents."}},"required":["year","age","contributionsCumulative","valueGross","vorabpauschaleTax"],"additionalProperties":false}},"finalValueGross":{"type":"number","description":"EUR, not cents."},"totalContributions":{"type":"number","description":"EUR, not cents."},"totalGrowth":{"type":"number","description":"EUR, not cents."},"finalValueAfterTax":{"type":"number","description":"EUR, not cents."},"taxOnSale":{"type":"number","description":"EUR, not cents."},"vorabpauschaleCredited":{"type":"number","description":"EUR, not cents."},"nvSavings":{"type":"number","description":"EUR, not cents."},"kindergeldEquivalent":{"type":"string","description":"Display text; use the numeric result fields for arithmetic."}},"required":["yearlyData","finalValueGross","totalContributions","totalGrowth","finalValueAfterTax","taxOnSale","vorabpauschaleCredited","nvSavings","kindergeldEquivalent"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/fire-rechner":{"get":{"operationId":"describeFireRechner","summary":"Input schema: FIRE Calculator","security":[],"responses":{"200":{"description":"Input JSON Schema and example with defaults, in the data/error/meta envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{}},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}},"post":{"operationId":"calculateFireRechner","summary":"FIRE Calculator","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","properties":{"monthlyExpenses":{"type":"number","minimum":1,"maximum":100000000,"default":2000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"currentPortfolio":{"type":"number","minimum":0,"maximum":100000000,"default":100000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":1500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"withdrawalRatePct":{"type":"number","minimum":2,"maximum":6,"default":3.5},"currentAge":{"type":"integer","minimum":18,"maximum":70,"default":30},"partTimeIncome":{"type":"number","minimum":0,"maximum":100000000,"default":1000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"targetRetirementAge":{"type":"integer","minimum":19,"maximum":80,"default":55},"variant":{"type":"string","enum":["regular","coast","barista"],"default":"regular"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false,"description":"Coast FIRE requires a future target age and a nominal return above 2% (the model inflation assumption)."},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":{"monthlyExpenses":2000,"currentPortfolio":100000,"monthlyContribution":1500,"annualReturnPct":7,"withdrawalRatePct":3.5,"currentAge":30,"partTimeIncome":1000,"targetRetirementAge":55,"variant":"regular","taxProfile":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000}},"locale":"en"}}}},"responses":{"200":{"description":"Calculated result, normalized inputs, assumptions and reproducible link.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["fire-rechner"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"monthlyExpenses":{"type":"number","minimum":1,"maximum":100000000,"default":2000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"currentPortfolio":{"type":"number","minimum":0,"maximum":100000000,"default":100000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":1500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"withdrawalRatePct":{"type":"number","minimum":2,"maximum":6,"default":3.5},"currentAge":{"type":"integer","minimum":18,"maximum":70,"default":30},"partTimeIncome":{"type":"number","minimum":0,"maximum":100000000,"default":1000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"targetRetirementAge":{"type":"integer","minimum":19,"maximum":80,"default":55},"variant":{"type":"string","enum":["regular","coast","barista"],"default":"regular"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false,"description":"Coast FIRE requires a future target age and a nominal return above 2% (the model inflation assumption)."},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"fireNumber":{"type":"number","description":"EUR, not cents."},"fireNumberPreTax":{"type":"number","description":"EUR, not cents."},"yearsToFire":{"type":["number","null"],"description":"Null means the target was not reached within the 50-year modeled horizon."},"monthlyContributionNeeded":{"type":"number","description":"EUR, not cents."},"coastFireNumber":{"type":["number","null"],"description":"Null when Coast FIRE does not apply."},"coastFireAge":{"type":["number","null"],"description":"Absolute age in years; null when Coast FIRE age is not applicable, including an already-funded portfolio."},"baristaIncomeNeeded":{"type":["number","null"],"description":"Annual part-time income in EUR; null when the Barista calculation does not apply."},"baristaPortfolioNeeded":{"type":["number","null"],"description":"Null when the Barista calculation does not apply."},"effectiveMultiplier":{"type":"number","description":"Multiple of annual expenses, not a percentage or EUR amount."}},"required":["fireNumber","fireNumberPreTax","yearsToFire","monthlyContributionNeeded","coastFireNumber","coastFireAge","baristaIncomeNeeded","baristaPortfolioNeeded","effectiveMultiplier"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"404":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Rate limited; honor Retry-After (seconds).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request or service error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/compare":{"post":{"operationId":"comparePublicCalculatorScenarios","summary":"Compare 2 to 10 independent scenarios for one calculator","security":[],"description":"Each scenario costs one rate-limit unit. All share a reference date and locale. HTTP 200 may contain per-scenario validation errors; inspect each item and summary. Unexpected engine errors fail the request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"calculator":{"type":"string","enum":["abgeltungssteuer","netto-dividende","vorabpauschale","thesaurierer-vs-ausschuetter","freistellungsauftrag","etf-sparplan","notgroschen","eigenkapital","rentenluecke","entnahmeplan","schenkungsteuer","junior-depot","fire-rechner"]},"scenarios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,40}$","description":"Unique caller-provided identifier, echoed in order."},"inputs":{"type":"object","additionalProperties":{},"description":"Independent inputs for this scenario. Omitted fields use calculator defaults; no inputs are inherited from other scenarios."}},"required":["id","inputs"],"additionalProperties":false},"minItems":2,"maxItems":10},"locale":{"type":"string","enum":["de","en"],"default":"en"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date in YYYY-MM-DD, year 0000 to 9949; leaves room for a 50-year savings projection. Defaults to the current UTC date."}},"required":["calculator","scenarios"],"additionalProperties":false},"example":{"calculator":"etf-sparplan","asOf":"2026-10-15","locale":"en","scenarios":[{"id":"monthly-300","inputs":{"monthly_rate":300,"annual_return":6,"annual_increase":0,"years":20}},{"id":"monthly-500","inputs":{"monthly_rate":500,"annual_return":6,"annual_increase":0,"years":20}},{"id":"monthly-700","inputs":{"monthly_rate":700,"annual_return":6,"annual_increase":0,"years":20}}]}}}},"responses":{"200":{"description":"Ordered results and per-scenario errors.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calculator":{"type":"string","enum":["abgeltungssteuer","netto-dividende","vorabpauschale","thesaurierer-vs-ausschuetter","freistellungsauftrag","etf-sparplan","notgroschen","eigenkapital","rentenluecke","entnahmeplan","schenkungsteuer","junior-depot","fire-rechner"]},"modelVersion":{"type":"string"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"summary":{"type":"object","properties":{"succeeded":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["succeeded","failed"],"additionalProperties":false},"scenarios":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"data":{"oneOf":[{"type":"object","properties":{"calculator":{"type":"string","enum":["abgeltungssteuer"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"kapitalertrag":{"type":"number","minimum":0,"maximum":100000000,"default":5000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"ertragsart":{"type":"string","enum":["general","aktienverkauf","dividende","etf"],"default":"general"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"brutto_ertrag":{"type":"number","description":"EUR, not cents."},"fsa_offset":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_ertrag":{"type":"number","description":"EUR, not cents."},"kapitalertragsteuer":{"type":"number","description":"EUR, not cents."},"solidaritaetszuschlag":{"type":"number","description":"EUR, not cents."},"kirchensteuer":{"type":"number","description":"EUR, not cents."},"gesamte_steuer":{"type":"number","description":"EUR, not cents."},"effektiver_steuersatz":{"type":"number","description":"Fraction: 0.25 means 25%."},"netto_ertrag":{"type":"number","description":"EUR, not cents."},"kirchensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"teilfreistellung_betrag":{"type":"number","description":"EUR, not cents."}},"required":["brutto_ertrag","fsa_offset","steuerpflichtiger_ertrag","kapitalertragsteuer","solidaritaetszuschlag","kirchensteuer","gesamte_steuer","effektiver_steuersatz","netto_ertrag","kirchensteuer_rate","teilfreistellung_betrag"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["netto-dividende"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"brutto_dividende":{"type":"number","minimum":0,"maximum":100000000,"default":500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"quelle":{"type":"string","enum":["aktie","etf_aktien","mischfonds"],"default":"aktie"},"isin":{"type":"string","pattern":"^[A-Z]{2}[A-Z0-9]{9}[0-9]$","description":"Optional issuer ISIN used for country-level withholding assumptions; not a live security lookup."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"brutto_dividende":{"type":"number","description":"EUR, not cents."},"teilfreistellung_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"teilfreistellung_betrag":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_betrag":{"type":"number","description":"EUR, not cents."},"steuer":{"type":"object","properties":{"brutto_ertrag":{"type":"number","description":"EUR, not cents."},"fsa_offset":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_ertrag":{"type":"number","description":"EUR, not cents."},"kapitalertragsteuer":{"type":"number","description":"EUR, not cents."},"solidaritaetszuschlag":{"type":"number","description":"EUR, not cents."},"kirchensteuer":{"type":"number","description":"EUR, not cents."},"gesamte_steuer":{"type":"number","description":"EUR, not cents."},"effektiver_steuersatz":{"type":"number","description":"Fraction: 0.25 means 25%."},"netto_ertrag":{"type":"number","description":"EUR, not cents."},"kirchensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."}},"required":["brutto_ertrag","fsa_offset","steuerpflichtiger_ertrag","kapitalertragsteuer","solidaritaetszuschlag","kirchensteuer","gesamte_steuer","effektiver_steuersatz","netto_ertrag","kirchensteuer_rate"],"additionalProperties":false},"quellensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"quellensteuer_betrag":{"type":"number","description":"EUR, not cents."},"anrechenbare_quellensteuer":{"type":"number","description":"EUR, not cents."},"erstattungsfaehige_quellensteuer":{"type":"number","description":"EUR, not cents."},"deutsche_reststeuer":{"type":"number","description":"EUR, not cents."},"quellensteuer_status":{"type":"string","enum":["credited","fund_level","none","unavailable"],"description":"unavailable means withholding was omitted because country assumptions are unavailable; none means no modeled investor withholding."},"netto_dividende":{"type":"number","description":"EUR, not cents."}},"required":["brutto_dividende","teilfreistellung_rate","teilfreistellung_betrag","steuerpflichtiger_betrag","steuer","quellensteuer_rate","quellensteuer_betrag","anrechenbare_quellensteuer","erstattungsfaehige_quellensteuer","deutsche_reststeuer","quellensteuer_status","netto_dividende"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["vorabpauschale"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"wert_jahresanfang":{"type":"number","minimum":0,"maximum":100000000,"default":10000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"wert_jahresende":{"type":"number","minimum":0,"maximum":100000000,"default":11500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"ausschuettungen":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","IMMOBILIENFONDS","IMMOBILIENFONDS_AUSLAND","SONSTIGE"],"default":"AKTIENFONDS"},"steuerjahr":{"anyOf":[{"type":"number","enum":[2023]},{"type":"number","enum":[2024]},{"type":"number","enum":[2025]},{"type":"number","enum":[2026]}],"default":2025,"description":"Only years with published Basiszins in the model are accepted. Single-position, full-year holding."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"basiszins":{"type":"number","description":"Percentage points: 4 means 4%."},"basisertrag":{"type":"number","description":"EUR, not cents."},"wertsteigerung":{"type":"number","description":"EUR, not cents."},"vorabpauschale_brutto":{"type":"number","description":"EUR, not cents."},"teilfreistellung_rate":{"type":"number","description":"Fraction: 0.25 means 25%."},"teilfreistellung_betrag":{"type":"number","description":"EUR, not cents."},"vorabpauschale_steuerpflichtig":{"type":"number","description":"EUR, not cents."},"steuer":{"type":"object","properties":{"brutto_ertrag":{"type":"number","description":"EUR, not cents."},"fsa_offset":{"type":"number","description":"EUR, not cents."},"steuerpflichtiger_ertrag":{"type":"number","description":"EUR, not cents."},"kapitalertragsteuer":{"type":"number","description":"EUR, not cents."},"solidaritaetszuschlag":{"type":"number","description":"EUR, not cents."},"kirchensteuer":{"type":"number","description":"EUR, not cents."},"gesamte_steuer":{"type":"number","description":"EUR, not cents."},"effektiver_steuersatz":{"type":"number","description":"Fraction: 0.25 means 25%."},"netto_ertrag":{"type":"number","description":"EUR, not cents."},"kirchensteuer_rate":{"type":"number","description":"Fraction: 0.25 means 25%."}},"required":["brutto_ertrag","fsa_offset","steuerpflichtiger_ertrag","kapitalertragsteuer","solidaritaetszuschlag","kirchensteuer","gesamte_steuer","effektiver_steuersatz","netto_ertrag","kirchensteuer_rate"],"additionalProperties":false}},"required":["basiszins","basisertrag","wertsteigerung","vorabpauschale_brutto","teilfreistellung_rate","teilfreistellung_betrag","vorabpauschale_steuerpflichtig","steuer"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["thesaurierer-vs-ausschuetter"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"initial_investment":{"type":"number","minimum":0,"maximum":100000000,"default":10000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthly_contribution":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annual_return":{"type":"number","minimum":1,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"distribution_yield":{"type":"number","minimum":0,"maximum":6,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"years":{"type":"integer","minimum":1,"maximum":40,"default":20},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","SONSTIGE"],"default":"AKTIENFONDS"},"reinvest_distributions":{"type":"boolean","default":true},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearly_data":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"thesaurierer_value":{"type":"number","description":"EUR, not cents."},"thesaurierer_vorabpauschale_tax":{"type":"number","description":"EUR, not cents."},"ausschuetter_value":{"type":"number","description":"EUR, not cents."},"ausschuetter_distribution_tax":{"type":"number","description":"EUR, not cents."},"ausschuetter_distributions_gross":{"type":"number","description":"EUR, not cents."},"ausschuetter_distributions_net":{"type":"number","description":"EUR, not cents."}},"required":["year","thesaurierer_value","thesaurierer_vorabpauschale_tax","ausschuetter_value","ausschuetter_distribution_tax","ausschuetter_distributions_gross","ausschuetter_distributions_net"],"additionalProperties":false}},"thesaurierer_final":{"type":"number","description":"EUR, not cents."},"ausschuetter_final":{"type":"number","description":"EUR, not cents."},"thesaurierer_advantage_eur":{"type":"number","description":"EUR, not cents."},"thesaurierer_advantage_pct":{"type":"number","description":"Percentage points: 4 means 4%."},"thesaurierer_total_taxes":{"type":"number","description":"EUR, not cents."},"ausschuetter_total_taxes":{"type":"number","description":"EUR, not cents."},"total_contributions":{"type":"number","description":"EUR, not cents."}},"required":["yearly_data","thesaurierer_final","ausschuetter_final","thesaurierer_advantage_eur","thesaurierer_advantage_pct","thesaurierer_total_taxes","ausschuetter_total_taxes","total_contributions"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["freistellungsauftrag"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"brokers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"zinsen":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"dividenden":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"vorabpauschale":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"realisierte_gewinne":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"current_fsa":{"type":"number","minimum":0,"maximum":2000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."}},"required":["name"],"additionalProperties":false},"minItems":1,"maxItems":6,"default":[{"name":"Broker 1","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0},{"name":"Broker 2","zinsen":0,"dividenden":0,"vorabpauschale":0,"realisierte_gewinne":0,"current_fsa":0}]},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"brokers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"expected_income":{"type":"number","description":"EUR, not cents."},"current_fsa":{"type":"number","description":"EUR, not cents."},"optimal_fsa":{"type":"number","description":"EUR, not cents."},"tax_with_current":{"type":"number","description":"EUR, not cents."},"tax_with_optimal":{"type":"number","description":"EUR, not cents."},"delta":{"type":"number","description":"EUR, not cents."}},"required":["name","expected_income","current_fsa","optimal_fsa","tax_with_current","tax_with_optimal","delta"],"additionalProperties":false}},"total_expected_income":{"type":"number","description":"EUR, not cents."},"total_fsa_available":{"type":"number","description":"EUR, not cents."},"total_fsa_optimal":{"type":"number","description":"EUR, not cents."},"total_tax_current":{"type":"number","description":"EUR, not cents."},"total_tax_optimal":{"type":"number","description":"EUR, not cents."},"savings":{"type":"number","description":"EUR, not cents."},"warnings":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["over_limit","under_utilised","january_risk"]},"message":{"type":"string"}},"required":["type","message"],"additionalProperties":false}}},"required":["brokers","total_expected_income","total_fsa_available","total_fsa_optimal","total_tax_current","total_tax_optimal","savings","warnings"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["etf-sparplan"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"initial_investment":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthly_rate":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annual_increase":{"type":"number","minimum":0,"maximum":10,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"annual_return":{"type":"number","minimum":1,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"years":{"type":"integer","minimum":1,"maximum":40,"default":20},"include_tax_drag":{"type":"boolean","default":false},"fondstyp":{"type":"string","enum":["AKTIENFONDS","MISCHFONDS","SONSTIGE"],"default":"AKTIENFONDS"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearly_data":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"contributions_cumulative":{"type":"number","description":"EUR, not cents."},"value_before_tax":{"type":"number","description":"EUR, not cents."},"value_after_tax":{"type":"number","description":"EUR, not cents."},"annual_contribution":{"type":"number","description":"EUR, not cents."},"vorabpauschale_tax":{"type":"number","description":"EUR, not cents."}},"required":["year","contributions_cumulative","value_before_tax","value_after_tax","annual_contribution","vorabpauschale_tax"],"additionalProperties":false}},"final_value":{"type":"number","description":"EUR, not cents."},"total_contributions":{"type":"number","description":"EUR, not cents."},"total_growth":{"type":"number","description":"EUR, not cents."},"total_taxes_paid":{"type":"number","description":"EUR, not cents."},"final_value_no_tax":{"type":"number","description":"EUR, not cents."},"tax_drag_eur":{"type":"number","description":"EUR, not cents."},"tax_drag_pct":{"type":"number","description":"Percentage points: 4 means 4%."}},"required":["yearly_data","final_value","total_contributions","total_growth","total_taxes_paid","final_value_no_tax","tax_drag_eur","tax_drag_pct"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["notgroschen"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"monthlyExpenses":{"type":"number","minimum":1,"maximum":100000000,"default":2500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"bufferMonths":{"anyOf":[{"type":"number","enum":[3]},{"type":"number","enum":[6]},{"type":"number","enum":[9]},{"type":"number","enum":[12]}],"default":6},"currentSavings":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlySavingsCapacity":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"parkingVehicle":{"type":"string","enum":["tagesgeld","geldmarkt_etf","festgeld_leiter"],"default":"tagesgeld"}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"targetAmount":{"type":"number","description":"EUR, not cents."},"deficit":{"type":"number","description":"EUR, not cents."},"monthsToTarget":{"type":"integer","minimum":0,"description":"Months to target, capped at 600; zero with a positive deficit and no saving capacity does not mean funded."},"targetUnreachable":{"type":"boolean","description":"The 600-month horizon was exhausted. Also inspect deficit and saving capacity when monthsToTarget is zero."},"targetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC modeled target date; only meaningful if the target is funded or reachable with positive saving capacity."},"expectedReturn":{"type":"number","description":"EUR, not cents."},"recommendedVehicle":{"type":"string","enum":["tagesgeld","geldmarkt_etf","festgeld_leiter"]}},"required":["targetAmount","deficit","monthsToTarget","targetUnreachable","targetDate","expectedReturn","recommendedVehicle"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["eigenkapital"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"purchasePrice":{"type":"number","minimum":0,"maximum":100000000,"default":350000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"bundesland":{"type":"string","enum":["baden-wuerttemberg","bayern","berlin","brandenburg","bremen","hamburg","hessen","mecklenburg-vorpommern","niedersachsen","nordrhein-westfalen","rheinland-pfalz","saarland","sachsen","sachsen-anhalt","schleswig-holstein","thueringen"],"default":"nordrhein-westfalen"},"eigenkapitalQuote":{"type":"number","minimum":10,"maximum":40,"default":20,"description":"Equity percentage points, e.g. 20 for 20%."},"currentSavings":{"type":"number","minimum":0,"maximum":100000000,"default":30000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlySavingsCapacity":{"type":"number","minimum":0,"maximum":100000000,"default":500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"savingsReturnPct":{"type":"number","minimum":0,"maximum":8,"default":4,"description":"Annual percentage points: 6 means 6%, not 0.06."}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"nebenkostenTotal":{"type":"number","description":"EUR, not cents."},"nebenkostenBreakdown":{"type":"object","properties":{"grunderwerbsteuer":{"type":"number","description":"EUR, not cents."},"notarGrundbuch":{"type":"number","description":"EUR, not cents."},"makler":{"type":"number","description":"EUR, not cents."}},"required":["grunderwerbsteuer","notarGrundbuch","makler"],"additionalProperties":false},"eigenkapitalRequired":{"type":"number","description":"EUR, not cents."},"totalUpfront":{"type":"number","description":"EUR, not cents."},"deficit":{"type":"number","description":"EUR, not cents."},"monthsToTarget":{"type":"integer","minimum":0,"description":"Months to target, capped at 600; zero with a positive deficit and no saving capacity does not mean funded."},"targetUnreachable":{"type":"boolean","description":"The 600-month horizon was exhausted. Also inspect deficit and saving capacity when monthsToTarget is zero."},"targetDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC modeled target date; only meaningful if the target is funded or reachable with positive saving capacity."},"monthlyMortgageEstimate":{"type":"number","description":"EUR, not cents."}},"required":["nebenkostenTotal","nebenkostenBreakdown","eigenkapitalRequired","totalUpfront","deficit","monthsToTarget","targetUnreachable","targetDate","monthlyMortgageEstimate"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["rentenluecke"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"currentAge":{"type":"integer","minimum":18,"maximum":65,"default":35},"retirementAge":{"type":"integer","minimum":55,"maximum":70,"default":67},"grossMonthlyIncome":{"type":"number","minimum":0,"maximum":100000000,"default":4000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"workingYearsSoFar":{"type":"integer","minimum":0,"maximum":50,"default":10},"desiredRetirementIncome":{"type":"number","minimum":0,"maximum":100000000,"default":2500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"existingPrivateProvision":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":300,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":6,"description":"Annual percentage points: 6 means 6%, not 0.06."}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"estimatedStatePension":{"type":"number","description":"Estimated monthly state pension, EUR."},"monthlyGap":{"type":"number","description":"EUR, not cents."},"annualGap":{"type":"number","description":"EUR, not cents."},"capitalNeeded":{"type":"number","description":"EUR, not cents."},"capitalNeededAfterExisting":{"type":"number","description":"EUR, not cents."},"monthlySavingsNeeded":{"type":"number","description":"EUR, not cents."},"surplusOrDeficit":{"type":"number","description":"EUR, not cents."},"yearsUntilRetirement":{"type":"number","description":"Elapsed years, possibly fractional."}},"required":["estimatedStatePension","monthlyGap","annualGap","capitalNeeded","capitalNeededAfterExisting","monthlySavingsNeeded","surplusOrDeficit","yearsUntilRetirement"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["entnahmeplan"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"portfolioValue":{"type":"number","minimum":0,"maximum":100000000,"default":500000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyWithdrawal":{"type":"number","minimum":0,"maximum":100000000,"default":2000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":5,"description":"Annual percentage points: 6 means 6%, not 0.06."},"inflationPct":{"type":"number","minimum":0,"maximum":5,"default":2,"description":"Annual percentage points: 6 means 6%, not 0.06."},"strategy":{"type":"string","enum":["constant_nominal","constant_real","percentage"],"default":"constant_nominal"},"percentageRate":{"type":"number","minimum":0.1,"maximum":20,"default":4,"description":"Annual withdrawal percentage points: 4 means 4%."},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearlyData":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"balanceStart":{"type":"number","description":"EUR, not cents."},"withdrawal":{"type":"number","description":"EUR, not cents."},"grossWithdrawal":{"type":"number","description":"EUR, not cents."},"taxPaid":{"type":"number","description":"EUR, not cents."},"growth":{"type":"number","description":"EUR, not cents."},"balanceEnd":{"type":"number","description":"EUR, not cents."}},"required":["year","balanceStart","withdrawal","grossWithdrawal","taxPaid","growth","balanceEnd"],"additionalProperties":false}},"yearsUntilDepletion":{"type":["number","null"],"description":"Null means no depletion within the modeled horizon; it does not show that the withdrawals last for life."},"totalWithdrawals":{"type":"number","description":"EUR, not cents."},"totalTaxPaid":{"type":"number","description":"EUR, not cents."},"effectiveWithdrawalRate":{"type":"number","description":"Percentage points: 4 means 4%."},"remainingAt80":{"type":["number","null"],"description":"EUR at age 80; null if that age is outside the modeled age/horizon."},"remainingAt90":{"type":["number","null"],"description":"EUR at age 90; null if that age is outside the modeled age/horizon."}},"required":["yearlyData","yearsUntilDepletion","totalWithdrawals","totalTaxPaid","effectiveWithdrawalRate","remainingAt80","remainingAt90"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["schenkungsteuer"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"relationship":{"type":"string","enum":["spouse","child","grandchild","sibling","other"],"default":"child"},"giftAmount":{"type":"number","minimum":0,"maximum":100000000,"default":100000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"previousGifts10y":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"numberOfDonors":{"type":"integer","minimum":1,"maximum":2,"default":1},"optimizeOverTime":{"type":"boolean","default":false},"totalToTransfer":{"type":"number","minimum":0,"maximum":10000000,"default":100000,"description":"Used only when optimizeOverTime is true. Prior gifts are not modeled by optimization."}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"anyOf":[{"type":"object","properties":{"freibetrag":{"type":"number","description":"EUR, not cents."},"totalFreibetrag":{"type":"number","description":"EUR, not cents."},"taxableAmount":{"type":"number","description":"EUR, not cents."},"taxRate":{"type":"number","description":"Fraction: 0.25 means 25%."},"taxDue":{"type":"number","description":"EUR, not cents."},"netGiftAmount":{"type":"number","description":"EUR, not cents."},"steuerklasse":{"type":"string","enum":["I","II","III"]},"optimalSchedule":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"amount":{"type":"number","description":"EUR, not cents."},"taxFree":{"type":"boolean"},"taxDue":{"type":"number","description":"EUR, not cents."}},"required":["year","amount","taxFree","taxDue"],"additionalProperties":false}},"totalTaxSaved":{"type":"number","description":"EUR, not cents."},"yearsNeeded":{"type":"number","description":"Elapsed years, possibly fractional."}},"required":["freibetrag","totalFreibetrag","taxableAmount","taxRate","taxDue","netGiftAmount","steuerklasse","optimalSchedule","totalTaxSaved","yearsNeeded"],"additionalProperties":false},{"type":"object","properties":{"freibetrag":{"type":"number","description":"EUR, not cents."},"totalFreibetrag":{"type":"number","description":"EUR, not cents."},"taxableAmount":{"type":"number","description":"EUR, not cents."},"taxRate":{"type":"number","description":"Fraction: 0.25 means 25%."},"taxDue":{"type":"number","description":"EUR, not cents."},"netGiftAmount":{"type":"number","description":"EUR, not cents."},"steuerklasse":{"type":"string","enum":["I","II","III"]}},"required":["freibetrag","totalFreibetrag","taxableAmount","taxRate","taxDue","netGiftAmount","steuerklasse"],"additionalProperties":false}],"description":"Scheduling mode adds optimalSchedule, totalTaxSaved and yearsNeeded. Single-gift mode returns the base fields."},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["junior-depot"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"childAge":{"type":"integer","minimum":0,"maximum":17,"default":0},"targetAge":{"type":"integer","minimum":1,"maximum":30,"default":18},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":100,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"initialDeposit":{"type":"number","minimum":0,"maximum":100000000,"default":0,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"useKindergeld":{"type":"boolean","default":false},"hasNVBescheinigung":{"type":"boolean","default":false},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"yearlyData":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":0,"description":"Year index from the start of the projection."},"age":{"type":"integer","description":"Child age in years."},"contributionsCumulative":{"type":"number","description":"EUR, not cents."},"valueGross":{"type":"number","description":"EUR, not cents."},"vorabpauschaleTax":{"type":"number","description":"EUR, not cents."}},"required":["year","age","contributionsCumulative","valueGross","vorabpauschaleTax"],"additionalProperties":false}},"finalValueGross":{"type":"number","description":"EUR, not cents."},"totalContributions":{"type":"number","description":"EUR, not cents."},"totalGrowth":{"type":"number","description":"EUR, not cents."},"finalValueAfterTax":{"type":"number","description":"EUR, not cents."},"taxOnSale":{"type":"number","description":"EUR, not cents."},"vorabpauschaleCredited":{"type":"number","description":"EUR, not cents."},"nvSavings":{"type":"number","description":"EUR, not cents."},"kindergeldEquivalent":{"type":"string","description":"Display text; use the numeric result fields for arithmetic."}},"required":["yearlyData","finalValueGross","totalContributions","totalGrowth","finalValueAfterTax","taxOnSale","vorabpauschaleCredited","nvSavings","kindergeldEquivalent"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false},{"type":"object","properties":{"calculator":{"type":"string","enum":["fire-rechner"]},"modelVersion":{"type":"string"},"inputs":{"type":"object","properties":{"monthlyExpenses":{"type":"number","minimum":1,"maximum":100000000,"default":2000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"currentPortfolio":{"type":"number","minimum":0,"maximum":100000000,"default":100000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"monthlyContribution":{"type":"number","minimum":0,"maximum":100000000,"default":1500,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"annualReturnPct":{"type":"number","minimum":0,"maximum":15,"default":7,"description":"Annual percentage points: 6 means 6%, not 0.06."},"withdrawalRatePct":{"type":"number","minimum":2,"maximum":6,"default":3.5},"currentAge":{"type":"integer","minimum":18,"maximum":70,"default":30},"partTimeIncome":{"type":"number","minimum":0,"maximum":100000000,"default":1000,"description":"EUR, numeric JSON value (not cents or a formatted string)."},"targetRetirementAge":{"type":"integer","minimum":19,"maximum":80,"default":55},"variant":{"type":"string","enum":["regular","coast","barista"],"default":"regular"},"taxProfile":{"type":"object","properties":{"bundesland":{"anyOf":[{"type":"string","enum":["Baden-Württemberg","Bayern","Berlin","Brandenburg","Bremen","Hamburg","Hessen","Mecklenburg-Vorpommern","Niedersachsen","Nordrhein-Westfalen","Rheinland-Pfalz","Saarland","Sachsen","Sachsen-Anhalt","Schleswig-Holstein","Thüringen"]},{"type":"null"},{"type":"null"}],"default":null},"kirchensteuer":{"type":"boolean","default":false},"filing_status":{"type":"string","enum":["single","joint"],"default":"single"},"sparerpauschbetrag_remaining":{"type":"number","minimum":0,"maximum":2000,"default":1000,"description":"Remaining EUR allowance for single-year tax calculations. Multi-year projections use the full annual statutory allowance based on filing_status."}},"default":{"bundesland":null,"kirchensteuer":false,"filing_status":"single","sparerpauschbetrag_remaining":1000},"additionalProperties":false}},"additionalProperties":false,"description":"Coast FIRE requires a future target age and a nominal return above 2% (the model inflation assumption)."},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC reference date for savings target dates; defaults to the current UTC date."},"result":{"type":"object","properties":{"fireNumber":{"type":"number","description":"EUR, not cents."},"fireNumberPreTax":{"type":"number","description":"EUR, not cents."},"yearsToFire":{"type":["number","null"],"description":"Null means the target was not reached within the 50-year modeled horizon."},"monthlyContributionNeeded":{"type":"number","description":"EUR, not cents."},"coastFireNumber":{"type":["number","null"],"description":"Null when Coast FIRE does not apply."},"coastFireAge":{"type":["number","null"],"description":"Absolute age in years; null when Coast FIRE age is not applicable, including an already-funded portfolio."},"baristaIncomeNeeded":{"type":["number","null"],"description":"Annual part-time income in EUR; null when the Barista calculation does not apply."},"baristaPortfolioNeeded":{"type":["number","null"],"description":"Null when the Barista calculation does not apply."},"effectiveMultiplier":{"type":"number","description":"Multiple of annual expenses, not a percentage or EUR amount."}},"required":["fireNumber","fireNumberPreTax","yearsToFire","monthlyContributionNeeded","coastFireNumber","coastFireAge","baristaIncomeNeeded","baristaPortfolioNeeded","effectiveMultiplier"],"additionalProperties":false},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri"},"methodology":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"}},"required":["calculator","methodology","documentation"],"additionalProperties":false}},"required":["calculator","modelVersion","inputs","asOf","result","assumptions","limitations","sources","links"],"additionalProperties":false}]},"error":{"type":"null"}},"required":["id","data","error"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_REQUEST"]},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["id","data","error"],"additionalProperties":false}]}}},"required":["calculator","modelVersion","asOf","summary","scenarios"],"additionalProperties":false},"error":{"type":"null"},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"400":{"description":"Invalid request, rate limit or server error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"413":{"description":"Invalid request, rate limit or server error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"429":{"description":"Invalid request, rate limit or server error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Invalid request, rate limit or server error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators/guide":{"get":{"operationId":"readPublicCalculatorAgentGuide","summary":"Agent quick-start guide","security":[],"responses":{"200":{"description":"Markdown guide with model selection and a complete generated request/response example.","content":{"text/markdown":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"meta":{"type":"object","additionalProperties":{}}},"required":["data","error","meta"]}}}}}}},"/api/v1/public/calculators":{"get":{"operationId":"listPublicCalculators","summary":"Discover calculator input schemas and examples","security":[],"responses":{"200":{"description":"Calculator catalog in the standard data/error/meta envelope."}}}}},"webhooks":{}}