API

Developer API

Obolus exposes a slim public API for payroll and tax-comparison workflows. MCP and OpenAPI describe the same published tool scope.

Status

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.

MCP

Use /api/mcp/public for general MCP clients; /api/mcp/claude remains a compatible alias. The ChatGPT app uses /api/mcp. The JSON tool-scope descriptor is at /api/mcp-discovery.

OpenAPI

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.

What is public?

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.

Agent discovery

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.

OpenAPI specification

Swagger-compatible OpenAPI specification for the Obolus REST API, including payroll and tax comparison schemas.

MCP discovery descriptor

Machine-readable descriptor for the public Obolus Model Context Protocol tool scope.

MCP Server for Tax Calculation

Remote Model Context Protocol (MCP) server for tax calculation, net salary workflows, and country tax comparison agents.

Public MCP Server for Tax Calculation

Agent-neutral read-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.

Claude MCP Server for Tax Calculation

Claude-compatible tool-only Model Context Protocol endpoint for Obolus payroll and tax comparison tools.

llms.txt

AI-system orientation file listing canonical Obolus pages and machine-readable API resources.

ChatGPT App

The Obolus ChatGPT App uses the same public MCP and API surface for global take-home-pay and salary comparisons. It is a technical integration of the Obolus calculation engine, not a separate consumer flow.

Which interface should you use?

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.

REST + OpenAPI

Recommended for standard integrations, dashboards, backend services, SDK generation, and conventional API clients.

MCP

Recommended for AI agents, tool runners, and systems that want tool discovery and invocation through one compact, machine-readable surface.

Authentication

The public read-only calculation tools work without a login or API key. API keys are optional for integrations; individual deployments may require one for certain endpoints. The preferred header is x-public-api-key.

  • Preferred header: x-public-api-key: <key>
  • Alternatives: x-api-key or Authorization: Bearer <API key> (compatibility alias, not an OAuth token)
  • OpenAPI, MCP discovery, and MCP transport may be open or key-protected depending on deployment settings
  • No browser login is required for the public MCP calculation tools
  • API keys are not self-service today; use the contact form if you need one

Versioning

The API uses contract versions instead of /v1 paths. API contract: 2.1.0; MCP tool contract: 1.0.1. Supported MCP protocol generations include 2025-11-25, 2026-07-28. Contract and protocol versions are separate.

Locale and URL structure

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 and website traffic

REST limits: taxcompare 20 requests / 5 minutes; berechne 60 requests / 5 minutes for cache misses. MCP transport: POST 200 requests / 5 minutes, GET 100 requests / 5 minutes; the two MCP endpoints have separate quotas. Additional per-tool or verified API-key limits apply only when enabled by server configuration. berechne cache hits may return before the REST limit check.

Key parameters

  • Supported country codes: DE, AT, US, CH, CA, AU, UK, IE
  • taxcompare in shared_gross mode: salary_ct (integer minor units), tax_year, countries, currency, and gross_mode
  • taxcompare in local_median_gross mode: tax_year, countries, currency, and gross_mode; no salary input is required
  • taxcompare currency accepts upper- or lower-case ISO codes such as EUR or eur; responses normalize them to lower-case
  • taxcompare gross_mode supports shared_gross and local_median_gross
  • tax_year is currently accepted as string or integer, typically 2026
  • berechne for DE: prefer country, tax_year and gross_salary with amount, currency and period; location, tax and social_security describe the profile. gross_salary.amount uses major currency units: 60000 means EUR 60,000 annual gross
  • Legacy berechne fields such as Personen[].Gehalt_ct remain available for existing integrations and use minor units: 6000000 cents means EUR 60,000 annual gross. Detailed cases for other countries currently use these legacy fields

Input and Output Parameter Matrix

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.

  • Input fields describe one shared request surface across multiple countries.
  • Output fields stay contract-stable even when their business meaning varies by country.
  • The full country-by-country matrix stays interactive and loads client-side after the page shell.

Key endpoints

/api/openapi

OpenAPI specification (Swagger-compatible)

/api/mcp-discovery

JSON discovery for tool scope, metadata, and docs

/api/mcp

Streamable HTTP MCP transport for ChatGPT and other MCP clients

/api/mcp/public

Public MCP calculation tools for all clients

/api/mcp/claude

Previous MCP path without ChatGPT UI metadata

/api/berechne

Direct payroll and tax call

/api/taxcompare

Direct salary compare call

Quickstart

  1. Send a public example request without a login; request an API key if needed
  2. Copy one of the example requests below and send it directly
  3. Inspect the response and validate it against your use case
  4. Use /api/openapi for full field details and schema-level reference

Responses and errors

Successful REST responses return tool-specific structures without a global ok/data envelope. MCP responses also include a summary with amounts in major currency units and, when available, calculation time, data and method versions, assumptions, warnings, and the engine_revision supplied by the backend. Results can change with tax data or exchange rates even for identical inputs. REST errors contain error and optionally details or restricted_fields.

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"
    }
  ]
}

Errors

Typical error codes:

  • 400 validation error
  • 401 missing or invalid key
  • 403 restricted field access
  • 429 rate limiting
  • 500 internal server error
{
  "error": "Invalid taxcompare payload.",
  "details": [
    "body.countries must contain at least 1 items."
  ]
}

Examples

curl -s https://www.obolusfinanz.de/api/openapi
curl -s https://www.obolusfinanz.de/api/mcp-discovery
curl -N -H "Accept: text/event-stream" https://www.obolusfinanz.de/api/mcp
curl -X POST https://www.obolusfinanz.de/api/taxcompare \
  -H "Content-Type: application/json" \
  -d '{
    "salary_ct": 6000000,
    "tax_year": "2026",
    "countries": ["DE", "AT", "AU"],
    "currency": "eur",
    "gross_mode": "shared_gross"
  }'
curl -X POST https://www.obolusfinanz.de/api/taxcompare \
  -H "Content-Type: application/json" \
  -d '{
    "tax_year": "2026",
    "countries": ["DE", "CH", "UK"],
    "currency": "eur",
    "gross_mode": "local_median_gross"
  }'
curl -X POST https://www.obolusfinanz.de/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "taxcompare",
      "arguments": {
        "salary_ct": 6000000,
        "tax_year": "2026",
        "countries": ["DE", "AT", "AU"],
        "currency": "eur",
        "gross_mode": "shared_gross"
      }
    }
  }'

Note

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.

API Usage & Guidelines

The Obolus API is designed to be simple, open, and useful for real-world financial tools.

You are free to use it for:

  • personal projects
  • prototypes and experiments
  • internal tools
  • public applications

Keep in mind:

  • Avoid excessive automated traffic or abuse
  • Do not resell raw API outputs as a standalone product
  • Use the API as part of a broader application or workflow

Attribution

If you use the API in a public-facing product, a small reference is appreciated:

Powered by Obolus

Stability

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.

Support

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.