{
  "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": "5.0.0",
  "apiVersion": "5.0.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": "Computes Cyprus personal income tax, GESY (National Health System) contributions, social insurance, and net (take-home) salary.",
      "requires_api_key": false,
      "version": "4.1.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "calculate_cyprus_state_pension",
      "description": "Estimates the Cyprus state (contributory) pension amount at retirement based on accumulated insurance units and contribution history.",
      "requires_api_key": false,
      "version": "3.1.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 to estimate the probability of not running out of money.",
      "requires_api_key": false,
      "version": "3.0.0",
      "since": "1.0.0",
      "status": "stable"
    },
    {
      "name": "calculate_cyprus_unemployment_benefit",
      "description": "Estimates the Cyprus unemployment benefit amount and separately assesses entitlement when qualifying facts are supplied.",
      "requires_api_key": false,
      "version": "3.1.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, including CPI indexation of the acquisition cost, lifetime first-disposal exemptions, the 20% CGT rate and the 0.4% property transfer fee.",
      "requires_api_key": false,
      "version": "2.1.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "simulate_mortgage",
      "description": "Simulates a Cyprus mortgage: monthly payment, outstanding principal, interest, and best/worst/varied variable-rate scenarios. Supports fixed then variable periods, monthly overpayments, lump sums and interest-only loans. Interest-only principal remains due at maturity. KFIK and cash-collateral configurations are not available through this API.",
      "requires_api_key": false,
      "version": "3.1.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 and investing the difference over a multi-year horizon, modelling the mortgage, purchase and selling costs, maintenance, rent inflation and investment returns, and reporting the breakeven year.",
      "requires_api_key": false,
      "version": "2.1.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": "2.1.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 disposable income, savings rate, the biggest optimisable leak and a surplus projection.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.5.0",
      "status": "stable"
    },
    {
      "name": "analyze_portfolio",
      "description": "Analyses an investment portfolio from its transaction history: net invested capital, current value, absolute return, chain-linked time-weighted return (TWR), CAGR on initial invested capital, per-sub-portfolio breakdown and allocation shares, with multi-currency support via per-transaction FX rates.",
      "requires_api_key": false,
      "version": "3.1.0",
      "since": "1.6.0",
      "status": "stable"
    },
    {
      "name": "simulate_life_insurance_flush",
      "description": "Simulates a Cyprus unit-linked life insurance policy year by year (monthly compounding, AUM and fixed fees, age-based mortality cost, 5% bid/ask spread when premiums are self-funded from the policy) and computes the tax-free 'safe limit' for partial surrenders under the 2026 rules, the tax due on any excess, and IRR with and without the premium tax relief.",
      "requires_api_key": false,
      "version": "4.1.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: finds the salary-vs-dividend split with maximum net cash in pocket.",
      "requires_api_key": false,
      "version": "2.1.0",
      "since": "1.17.0",
      "status": "stable"
    }
  ]
}