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

MCP describes tools, discovery, and invocation in an agent-friendly format. Use /api/mcp when a client first needs resources, tools, and invocation schemas.

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.

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

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.

  • - Preferred header: x-public-api-key: <key>
  • - Alternatives supported: x-api-key or Authorization: Bearer <token>
  • - OpenAPI and MCP discovery may be open or key-protected depending on deployment settings
  • - For stable integrations, always use an API key
  • - API keys are not self-service today; access and higher limits currently require direct contact

Versioning

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.

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

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.

Key parameters

  • - Supported country codes: DE, AT, US, CH, CA, AU, UK, IE
  • - Minimum fields for taxcompare: annual_gross, tax_year, countries, currency
  • - taxcompare currency accepts lower-case ISO values such as eur, usd, chf, cad, aud, gbp
  • - taxcompare gross_mode supports shared_gross and local_median_gross
  • - tax_year is currently accepted as string or integer, typically 2026
  • - berechne expects many monetary amounts in minor units such as cent

Key endpoints

/api/openapi

OpenAPI specification (Swagger-compatible)

/api/mcp

MCP discovery and gateway

/api/berechne

Direct payroll and tax call

/api/taxcompare

Direct salary compare call

Quickstart

  1. 1. Request an API key if you want production usage or higher limits
  2. 2. Copy one of the example requests below and send it directly
  3. 3. Inspect the response and validate it against your use case
  4. 4. Use /api/openapi for full field details and schema-level reference

Responses and errors

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": 0.3375,
      "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
curl -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 '{
    "tool": "taxcompare",
    "arguments": {
      "annual_gross": 60000,
      "tax_year": "2026",
      "countries": ["DE", "AT", "AU"],
      "currency": "eur"
    }
  }'

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.

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.