API and MCP

API - simulation, solvers, insights and jobs

Deterministic projections with compact views, Monte Carlo and solver jobs with polling, server-sent events and cancellation, insights, and moving-country routes.

All paths are under /api/v1. These routes need read or simulate scope.

Deterministic projection

POST /plans/{id}/simulate runs the engine. Without view you get the full result (every period, ledger and trace: large). With view you get a compact one:

{ "trace": "off",
  "view": { "basis": "real", "fromYear": 2030, "toYear": 2060, "everyNYears": 5,
            "series": ["netWorth", "liquidNetWorth", "spending", "taxes", "shortfall"],
            "accountIds": ["acc-brokerage"], "include": ["summary", "milestones", "warnings"] } }

series is any of netWorth, liquidNetWorth, assets, liabilities, portfolio, cash, realAssets, income, passiveIncome, expenses, spending, taxes, contributions, withdrawals, savingsRate, withdrawalRate and shortfall. POST /simulate is stateless: send a full simulation input and nothing is stored.

Results are cached per plan id, plan version, options, household version and engine version, so an edit never serves a stale result.

Jobs

POST /plans/{id}/monte-carlo, POST /plans/{id}/historical, the solvers, guardrails, tax strategy and some insights run in worker threads (GLIDEWORTH_MAX_JOBS at a time, default 2) and return 202 with a job.

Route Purpose
GET /jobs, GET /jobs/{id} status is queued, running, succeeded, failed or cancelled; progress runs 0 to 1.
GET /jobs/{id}/events Server-sent events: status, progress, then done. The data is the job JSON.
GET /jobs/{id}/result The result. Monte Carlo results are thinned by default; ask for more with ?detail=full, ?metrics=, ?percentiles= or ?everyNYears=.
POST /jobs/{id}/cancel Stop the job and its worker threads.

Add ?wait=<seconds> (up to 120) to the start request to block until the job finishes and get the finished job back. Browsers’ EventSource cannot set an Authorization header but does send the session cookie; elsewhere use curl -N or fetch streaming. A failed job carries a typed error, and a job interrupted by a restart fails with INTERRUPTED.

A large run is split across worker threads (the lesser of the CPU count and 4, overridable with GLIDEWORTH_MC_SHARDS, never fewer than 200 trials each) and gives the same result as a single-threaded run with the same seed. Without settings.seed, a fixed default seed is used; "randomSeed": true draws a fresh one and skips the cache.

Solvers

All are jobs with the same ?wait= and a monteCarlo override such as {"monteCarlo": {"trials": 200}}, plus maxEvaluations and targetSuccessRate.

Route Extra body Answers
POST /plans/{id}/solve/max-spending expenseIds How much can I spend?
POST /plans/{id}/solve/earliest-retirement milestoneId Earliest retirement month.
POST /plans/{id}/solve/required-savings flowId How much must I save?
POST /plans/{id}/solve/required-portfolio accountIds How much do I need?
POST /plans/{id}/solve/safe-withdrawal-rate years, accountIds Highest constant withdrawal rate.
POST /plans/{id}/solve/goal-seek variable, objective, direction, bounds Any variable against any objective.
POST /plans/{id}/solve/tax-strategy objective, candidates Compare tax strategies.

Insights

Route Purpose
POST /plans/{id}/insights/explain, /explain-year, /explain-years, /explain-difference Why the plan ended up here, where the money went, why two plans differ.
POST /plans/{id}/insights/audit Modelling mistakes, with severities and ready-made fixes.
POST /plans/{id}/insights/sensitivity Tornado data; metric can be successRate (a job).
POST /plans/{id}/insights/guardrails, /guyton-klinger Spending guardrails.
POST /plans/{id}/insights/debt-payoff, /income-by-tax-rate, /strategy-matrix Debt strategies, income by marginal rate, strategies against metrics (a job).
GET /plans/{id}/tax-breakdown Taxes by year, jurisdiction and kind.
POST /insights/compare, POST /insights/sepp-comparison Compare 2 to 6 plans; 72(t) methods.

Moving country

GET /plans/{id}/residency-timeline, GET /plans/{id}/cross-border/items, POST /plans/{id}/insights/explain-taxation, POST /plans/{id}/insights/stay-or-move, GET /plans/{id}/tax-breakdown/by-country, and the rule tables GET /cross-border/countries, /cross-border/non-resident-rules/{country}, /cross-border/treaties, /cross-border/treaties/{a}/{b}, /cross-border/wrappers and /cross-border/simplifications, plus POST /cross-border/explain. Stay-or-move runs two deterministic projections and answers inline.

Last checked against the code on .