API
Obolus exposes a slim public API for payroll and tax-comparison workflows. MCP and OpenAPI describe the same published tool scope.
The Developer API is intentionally slim and currently focused on payroll and tax-compare workflows. The scope is expanded carefully and is currently in early public status.
The actual remote MCP transport lives at /api/mcp and is the endpoint intended for ChatGPT, agents, and other MCP clients. The JSON scope description is exposed separately at /api/mcp-discovery.
OpenAPI is the REST-oriented specification of the same public tools. Use /api/openapi for Swagger-compatible docs, client generation, and formal request/response schemas.
The current public scope includes MCP and OpenAPI discovery plus the two tools berechne, taxcompare. Cockpit, Budget, and Invest stay product-flow features and are intentionally not published as public API endpoints.
For most public integrations, REST through OpenAPI plus direct tool calls is the right default. MCP is the better layer for agents, tool runtimes, and clients that want discovery and invocation through a single gateway-style interface.
Recommended for standard integrations, dashboards, backend services, SDK generation, and conventional API clients.
Recommended for AI agents, tool runners, and systems that want tool discovery and invocation through one compact, machine-readable surface.
API keys are intended for production usage and should be used in all requests, even if some endpoints may currently be reachable without auth. For public integrations, x-public-api-key is the preferred header.
The public API currently uses contract versioning rather than /v1 path versioning. API version: 2.1.0. MCP version: 1.0.1. Breaking changes ship with a new contract version; additive changes can happen within the same version.
The API itself is locale-neutral and lives under /api/... without a locale prefix. The /de, /en, and /tr paths are for documentation only, not for API execution.
Rate limits currently apply at route level and are enforced the same way when website traffic and external API usage hit the same endpoint. taxcompare is currently limited to 20 requests per 5 minutes per route; berechne is more generous at 1000 requests per 5 minutes for cache misses. berechne cache hits can return before the actual rate-limit check.
For search and quick orientation, the short version is enough: the same public tool contracts span all supported countries, while the meaning of individual payroll fields still changes by tax system.
OpenAPI specification (Swagger-compatible)
JSON discovery for tool scope, metadata, and docs
Streamable HTTP MCP transport for ChatGPT and other MCP clients
Direct payroll and tax call
Direct salary compare call
Successful responses do not use a global ok/data envelope and instead return tool-specific response structures directly. Responses are deterministic for identical inputs within the same contract version. Response structures remain stable within the same contract version. Error responses are intentionally slim and return error plus optional details or restricted_fields depending on the failure type.
Example response (taxcompare, shortened):
{
"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"
}
]
}Typical error codes:
{
"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 and OpenAPI are generated from the same contract source. That contract source is the authoritative basis of the public API. Backend changes should always ship together with the public contract.
The Obolus API is designed to be simple, open, and useful for real-world financial tools.
If you use the API in a public-facing product, a small reference is appreciated:
The API is actively evolving. Core endpoints are kept stable, while response structures may improve over time. For production usage, we recommend handling responses defensively.
For public API questions, API key requests, manual access, or higher throughput, use the contact or feedback flow on the website to get API keys or adjust limits.