API
Obolus stellt eine schlanke öffentliche API für Payroll- und Tax-Compare-Workflows bereit. MCP und OpenAPI beschreiben denselben freigegebenen Tool-Scope.
Die Developer API ist bewusst schlank gehalten und deckt derzeit Payroll- und Tax-Compare-Workflows ab. Der Scope wird kontrolliert erweitert und befindet sich aktuell im Early Public Status.
Der eigentliche Remote-MCP-Transport liegt unter /api/mcp und ist für ChatGPT, Agents und andere MCP-Clients gedacht. Die JSON-Beschreibung des freigegebenen Scopes liegt getrennt unter /api/mcp-discovery.
OpenAPI ist die REST-orientierte Spezifikation derselben öffentlichen Tools. Verwende /api/openapi für Swagger-kompatible Dokumentation, Client-Generierung und formale Request/Response-Schemas.
Der aktuelle Public Scope umfasst Discovery über MCP und OpenAPI sowie die beiden Tools berechne und taxcompare. Cockpit-, Budget- und Invest-Interaktionen bleiben bewusst Produkt-Flow und werden nicht als Public API veröffentlicht.
Obolus publishes a Model Context Protocol (MCP) server for tax calculation, a Claude-compatible MCP endpoint, and an OpenAPI specification so AI agents, developer tools, and LLM crawlers can discover the public payroll and tax comparison API surface.
Swagger-compatible OpenAPI specification for the Obolus REST API, including payroll and tax comparison schemas.
Machine-readable descriptor for the public Obolus Model Context Protocol tool scope.
Remote Model Context Protocol (MCP) server for tax calculation, net salary workflows, and country tax comparison agents.
Claude-compatible tool-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.
AI-system orientation file listing canonical Obolus pages and machine-readable API resources.
Die Obolus ChatGPT App nutzt dieselbe öffentliche MCP- und API-Oberfläche für globale Netto- und Gehaltsvergleiche. Sie ist eine technische Integration des Obolus-Rechenkerns, kein separater Consumer-Flow.
Für die meisten öffentlichen Integrationen ist REST über OpenAPI plus direkter Tool-Call die richtige Wahl. MCP ist die bessere Schicht für Agenten, Tool-Runtime-Systeme und Clients, die Discovery und Invocation über einen Gateway-Ansatz brauchen.
Empfohlen für klassische Integrationen, Dashboards, Backend-Services, SDK-Generierung und konventionelle API-Clients.
Empfohlen für AI-Agents, Tool-Runner und Systeme, die Tool-Discovery und Invocation über eine kompakte, maschinenlesbare Beschreibung verwenden wollen.
API-Keys sind für produktive Nutzung vorgesehen und sollten in allen Requests verwendet werden, auch wenn einzelne Endpunkte aktuell noch ohne Auth erreichbar sein können. Für öffentliche Integrationen ist x-public-api-key der bevorzugte Header.
Die öffentliche API wird aktuell über die Contract-Version statt über /v1-URLs versioniert. API-Version: 2.1.0. MCP-Version: 1.0.1. Nicht abwärtskompatible Änderungen werden mit einer neuen Contract-Version ausgerollt; additive Erweiterungen können innerhalb derselben Version erfolgen.
Die API selbst ist sprachneutral und lebt unter /api/..., nicht unter einem Locale-Präfix. Die /de-, /en- und /tr-Pfade gelten für die Dokumentation, nicht für die API-Endpunkte.
Rate Limits gelten auf Route-Ebene und werden aktuell unabhängig von der Quelle angewendet, wenn Website-Traffic und externe API-Nutzung dieselben Endpunkte nutzen. Für taxcompare gelten aktuell 20 Requests pro 5 Minuten je Route; berechne ist großzügiger und nutzt 1000 Requests pro 5 Minuten für Cache-Misses. Cache-Hits bei berechne können vor der eigentlichen Limit-Prüfung beantwortet werden.
Für Suchmaschinen und die erste Orientierung reicht die Kurzfassung: dieselben Tool-Verträge decken alle unterstützten Länder ab, aber die Bedeutung einzelner Payroll-Felder unterscheidet sich je nach Steuersystem.
OpenAPI-Spezifikation (Swagger-kompatibel)
JSON-Discovery für Tool-Scope, Metadaten und Docs
Streamable HTTP MCP-Transport für ChatGPT und andere MCP-Clients
/api/berechneDirekter Payroll- und Tax-Call
/api/taxcompareDirekter Salary-Compare-Call
Erfolgsantworten verwenden kein globales ok/data-Envelope, sondern liefern direkt tool-spezifische Response-Strukturen. Für identische Inputs innerhalb derselben Contract-Version sind Responses deterministisch. Innerhalb derselben Contract-Version bleiben Response-Strukturen stabil. Fehler folgen einem schlanken JSON-Format mit error und optional details oder restricted_fields.
Beispielantwort (taxcompare, gekürzt):
{
"results": [
{
"country": "DE",
"net": 39750,
"tax": 13000,
"social_contributions": 7250,
"effective_rate": 33.75,
"input_annual_gross": 60000,
"input_currency": "eur",
"comparison_basis": "shared_gross"
}
]
}Typische Fehlercodes:
{
"error": "Invalid taxcompare payload.",
"details": [
"body.countries must contain at least 1 items."
]
}curl -s https://www.obolusfinanz.de/api/openapicurl -s https://www.obolusfinanz.de/api/mcp-discoverycurl -N -H "Accept: text/event-stream" https://www.obolusfinanz.de/api/mcpcurl -X POST https://www.obolusfinanz.de/api/taxcompare \
-H "Content-Type: application/json" \
-H "x-public-api-key: YOUR_API_KEY" \
-d '{
"annual_gross": 60000,
"tax_year": "2026",
"countries": ["DE", "AT", "AU"],
"currency": "eur"
}'curl -X POST https://www.obolusfinanz.de/api/mcp \
-H "Content-Type: application/json" \
-H "x-public-api-key: YOUR_API_KEY" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "taxcompare",
"arguments": {
"annual_gross": 60000,
"tax_year": "2026",
"countries": ["DE", "AT", "AU"],
"currency": "eur"
}
}
}'MCP und OpenAPI werden aus derselben Vertragsquelle erzeugt. Diese Contract-Quelle ist die verbindliche Grundlage der öffentlichen API. Änderungen am Backend sollten immer gemeinsam mit dem öffentlichen Contract ausgeliefert werden.
Die Obolus API ist bewusst einfach, offen und für reale Finanz-Tools gedacht.
Wenn du die API in einem öffentlich sichtbaren Produkt nutzt, freuen wir uns über einen kleinen Hinweis:
Die API entwickelt sich aktiv weiter. Kern-Endpunkte bleiben stabil, während Response-Strukturen sich im Detail verbessern können. Für produktive Integrationen empfehlen wir, Responses defensiv zu verarbeiten.
Bei Fragen zur öffentlichen API, für API-Key-Anfragen, manuelle Freischaltung oder für höheren Durchsatz nutze bitte das Kontakt- oder Feedback-Formular auf der Website, um API-Keys zu erhalten oder Limits anzupassen.