{
  "name": "PoliErgaleio Public Calculation API",
  "description": "Bilingual (EN/EL) Cyprus financial calculation tools exposed as MCP tools and REST endpoints: income tax, state pension, retirement stress test, unemployment benefit, Cyprus capital gains tax, mortgage simulation, employee stock options, rent vs buy, EV vs petrol savings, investment vehicle comparison, monthly budget planning, pension reference data, pension statement parsing, and saved-calculation retrieval.",
  "mcp_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/mcp",
  "tools_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/tools",
  "documentation_url": "https://poliergaleio.com/developers",
  "documentation_txt": "https://poliergaleio.com/developers.txt",
  "api_key_url": "https://poliergaleio.com/profile",
  "authentication": {
    "type": "api_key",
    "header": "x-api-key",
    "obtain_url": "https://poliergaleio.com/profile"
  },
  "version": "18.1.0",
  "apiVersion": "18.1.0",
  "version_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/version",
  "latest_changes_url": "https://poliergaleio.com/developers",
  "versioning": {
    "version_header": "X-API-Version",
    "version_body_field": "apiVersion",
    "note": "Every JSON response carries the current API version in the X-API-Version header and apiVersion body field. GET /version returns the current version and changelog. Breaking changes are announced with Deprecation and Sunset headers plus a plain-language notice field in the response body; update by re-importing the OpenAPI spec (ChatGPT Actions) or reconnecting the MCP server (Claude/Cursor)."
  },
  "schemas_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/schemas",
  "saved_calculations_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/saved-calculations",
  "request_tracing": {
    "header": "X-Request-Id",
    "echoed": true,
    "body_field": "requestId"
  },
  "guest_identifier": {
    "header": "x-guest-id",
    "optional": true,
    "note": "Opaque client id; only its hash is stored, used for anonymous rate limiting."
  },
  "whoami_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/whoami",
  "openapi": "https://poliergaleio.com/poliergaleio-openapi.json",
  "operator": {
    "name": "PoliErgaleio",
    "url": "https://poliergaleio.com",
    "email": "hello@poliergaleio.com"
  },
  "verification": {
    "whoami_endpoint": "https://gpkpjfdlbsuyevfdsnbq.supabase.co/functions/v1/public-api/whoami",
    "browser_checker": "https://poliergaleio.com/developers/verify",
    "key_check_header": "x-api-key"
  },
  "downloads": {
    "postman_collection": "https://poliergaleio.com/poliergaleio-api.postman_collection.json",
    "postman_environment": "https://poliergaleio.com/poliergaleio-api.postman_environment.json",
    "openapi": "https://poliergaleio.com/poliergaleio-openapi.json",
    "plain_text": "https://poliergaleio.com/developers.txt"
  },
  "tools": [
    {
      "name": "calculate_cyprus_income_tax",
      "description": "Calculates Cyprus income tax, employee/self-employed SI, GESY and take-home pay. Employee SI and first-employment relief use qualifying employment remuneration only; rent does not increase employee SI. GESY uses the shared €180,000 personal ceiling.",
      "requires_api_key": false,
      "version": "9.0.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "calculate_cyprus_state_pension",
      "description": "Estimates the Cyprus state (contributory) pension amount at retirement using official contribution schedules and current 2026 pension income-tax bands, based on accumulated insurance units and contribution history.",
      "requires_api_key": false,
      "version": "6.0.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "run_retirement_stress_test",
      "description": "Runs a deterministic projection plus Monte Carlo simulation of a retirement savings plan. Seeded market and medical paths use independent random streams. Age-keyed returnOverrides replace returns in both calculation modes; nonDepletionProbability always reports basic no-shortfall success, while successProbability also applies supplied successCriteria.",
      "requires_api_key": false,
      "version": "6.2.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "calculate_cyprus_unemployment_benefit",
      "description": "Estimates the Cyprus unemployment benefit using statutory percentage-point dependant additions and a capped earnings-related supplement, and separately assesses entitlement when qualifying facts are supplied.",
      "requires_api_key": false,
      "version": "5.0.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "get_pension_reference_data",
      "description": "Returns official Cyprus Social Insurance reference tables for a given year.",
      "requires_api_key": false,
      "version": "2.1.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "parse_pension_statement",
      "description": "Extracts structured contribution history from pasted Cyprus Social Insurance Services pension statement text.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "calculate_cyprus_capital_gains",
      "description": "Calculates Cyprus Capital Gains Tax on an immovable property disposal using 2025 or 2026 rules, including CPI indexation, year-specific lifetime exemptions, the 20% CGT rate and the 0.4% property transfer fee.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "simulate_mortgage",
      "description": "Simulates a Cyprus mortgage with a payment schedule that reconciles paid amounts to principal and interest. Supports fixed then variable periods, monthly overpayments, lump sums and interest-only loans; interest-only minimum payments track the remaining balance, with principal due at maturity. KFIK and cash-collateral configurations are not available through this API.",
      "requires_api_key": false,
      "version": "4.0.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "calculate_stock_options",
      "description": "Compares the Cyprus tax on an employee stock option exercise under the 2025 benefit-in-kind rules (progressive income tax) and the 2026 approved-scheme rules (flat 8% within caps), including the 2x salary annual cap and the €1m rolling 10-year lifetime cap.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "compare_rent_vs_buy",
      "description": "Compares buying a home against renting using actual period mortgage payments and symmetric investment of whichever scenario has lower cash costs. Mortgage contributions stop after payoff; purchase/sale costs, maintenance, rent inflation and investment returns are included.",
      "requires_api_key": false,
      "version": "4.0.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "calculate_ev_savings",
      "description": "Compares the annual running cost of an electric car against a petrol/diesel car in Cyprus, splitting charging between spare solar production, home grid electricity and public chargers, and reporting yearly savings and payback on the extra purchase cost.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "compare_investment_vehicles",
      "description": "Compares a taxable investment (option 1) against a tax-deductible vehicle such as a provident fund or life-insurance savings plan (option 2), matching the true out-of-pocket cost of both and applying entry/exit fees, AUM fees, commission and exit tax.",
      "requires_api_key": false,
      "version": "3.0.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "plan_monthly_budget",
      "description": "Builds a monthly budget from a list of expenses at any frequency: normalises everything to a monthly basis, tiers each item (T1 fixed essentials, T2 variable essentials, T3 lifestyle, T4 discretionary), and returns cash-basis disposable income, savings rate after expenses and investments, the biggest optimisable leak and a surplus projection; deficit months clamp savings at zero.",
      "requires_api_key": false,
      "version": "4.0.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "analyze_portfolio",
      "description": "Analyzes portfolio transactions or holdings: invested capital, value, absolute/TWR returns, eligible single-deposit CAGR, sub-portfolio allocation, and FX conversion. CAGR is null with a reason after multiple contributions or withdrawals.",
      "requires_api_key": false,
      "version": "4.0.0",
      "since": "1.6.0",
      "status": "stable"
    },
    {
      "name": "simulate_life_insurance_flush",
      "description": "Simulates a Cyprus unit-linked life insurance policy and calculates tax and returns from executed withdrawals only. Requests above available funds are capped and flagged; self-funded surrender taxes are included in household cash flows and IRR.",
      "requires_api_key": false,
      "version": "5.0.0",
      "since": "1.6.0",
      "status": "stable"
    },
    {
      "name": "audit_mortgage_statement",
      "description": "Forensic audit of a mortgage statement: replays the loan day by day and grid-searches the bank's interest convention (Actual/365, Actual/360 or Actual/Actual day count; monthly, semi-annual or annual capitalisation; exact or 2-decimal daily rounding), ranks candidates by RMS error against the bank's own running balance, and reports the interest overcharge implied by the best fit.",
      "requires_api_key": false,
      "version": "2.1.0",
      "since": "1.6.0",
      "status": "stable"
    },
    {
      "name": "list_saved_calculations",
      "description": "Lists metadata of an authenticated user's saved calculations by calculator type.",
      "requires_api_key": true,
      "version": "2.1.0",
      "since": "1.1.0",
      "status": "stable"
    },
    {
      "name": "load_saved_calculation",
      "description": "Loads one saved calculation belonging to the authenticated API key's user.",
      "requires_api_key": true,
      "version": "2.1.0",
      "since": "1.1.0",
      "status": "stable"
    },
    {
      "name": "save_calculation",
      "description": "Saves a calculator scenario to the authenticated user's stored history.",
      "requires_api_key": true,
      "version": "2.1.0",
      "since": "1.11.0",
      "status": "stable"
    },
    {
      "name": "update_calculation",
      "description": "Renames a saved calculation and/or replaces its inputs (recomputing results).",
      "requires_api_key": true,
      "version": "2.1.0",
      "since": "1.11.0",
      "status": "stable"
    },
    {
      "name": "delete_saved_calculation",
      "description": "Deletes one saved calculation belonging to the authenticated API key's user.",
      "requires_api_key": true,
      "version": "2.1.0",
      "since": "1.11.0",
      "status": "stable"
    },
    {
      "name": "compare_saved_calculations",
      "description": "Diffs two saved calculations (inputs and results) field by field.",
      "requires_api_key": true,
      "version": "2.1.0",
      "since": "1.11.0",
      "status": "stable"
    },
    {
      "name": "parse_portfolio_csv",
      "description": "Turns pasted broker CSV or ledger text into analyze_portfolio transactions.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.11.0",
      "status": "stable"
    },
    {
      "name": "parse_mortgage_statement_text",
      "description": "Turns pasted bank mortgage-statement rows into audit_mortgage_statement inputs.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.11.0",
      "status": "stable"
    },
    {
      "name": "optimize_company_director_remuneration",
      "description": "Optimizes Cyprus LTD company-director remuneration for monetary inputs up to €1,000,000, with a fixed solver evaluation budget.",
      "requires_api_key": false,
      "version": "3.0.0",
      "since": "1.17.0",
      "status": "stable"
    }
  ]
}
