API and MCP

API - households, finances and plans

Routes for households and people, accounts, real assets and debts, plan collections and settings, version history and undo, and branches.

All paths are under /api/v1. Read scope covers GET; writes need write scope and the editor or owner role. For conventions see API overview.

Households and people

Route Purpose
GET/POST /households List or create.
GET/PUT/PATCH/DELETE /households/{id} One household. PUT also accepts the whole current-finances body.
/households/{id}/people[/{personId}], /households/{id}/dependents[/{id}] CRUD. Adding a second person switches the household to couple mode.
GET/PUT/PATCH /households/{id}/people/{personId}/cross-border Citizenships, US green card, residence history and state-pension records, checked as a unit.
PUT /households/{id}/reorder/{collection} Display order. collection is accounts, real-assets, debts or plans.

Current finances

Route Purpose
/households/{id}/accounts, /real-assets, /debts List, create, get, PUT, PATCH, DELETE by id. Delete is 409 IN_USE while a plan references the item, unless force=true; prefer archived: true.
PUT /households/{id}/current-finances Replace the people, accounts, real assets and debts in one validated, all-or-nothing write. A stale If-Match changes nothing.
POST /households/{id}/balances Update many balances atomically (accounts, real-asset values and loan balances, debts). Unknown ids change nothing and return 404.
GET/POST/PUT /households/{id}/fx-rates, DELETE /households/{id}/fx-rates/{FROM-TO} Exchange-rate pairs.
/households/{id}/snapshots and .../snapshots/record, .../snapshots/bulk Progress snapshots.

A balance write that moves a balance creates or updates today’s automatic snapshot, at most one a day, when settings.autoProgressSnapshots is true (the default).

Plans

Route Purpose
GET/POST /plans List or create.
GET/PUT/PATCH/DELETE /plans/{id} One plan. PUT requires If-Match. PATCH takes JSON Patch with id-addressed items.
POST /plans/{id}/duplicate, /archive, /unarchive, /set-main Plan actions.
/plans/{id}/income, /expenses, /milestones, /flows, /planned-accounts, /planned-real-assets, /residency Collections: list, add, get, PUT, PATCH, DELETE by id.
PUT /plans/{id}/reorder/{collection} Reorder. For flows, the order is the funding priority.
/plans/{id}/assumptions, /tax-settings, /withdrawal-strategy, /drawdown, /flex-spending, /risk-guardrails, /tax-strategy, /monte-carlo-settings, /leftover Singletons with GET, PUT, PATCH, DELETE. DELETE removes optional ones and resets the others to defaults.

History and undo

Route Purpose
GET /plans/{id}/versions Every version with its actor and message.
GET /plans/{id}/versions/{n} One version.
GET /plans/{id}/versions/{n}/diff?against=current A readable diff.
POST /plans/{id}/versions/{n}/restore Writes the old content as a new version. History is append-only.

Branches

Route Purpose
POST /plans/{id}/branches Create a branch, optionally with an initial patch.
GET /plans/{id}/branches List branches.
GET /plans/{id}/diff A branch against its parent, with outcomes.
POST /plans/{id}/merge Merge a branch back.

A branch stores only its differences from the parent, follows the parent (or pins its version), is rebuilt whenever the parent changes, and can be merged back or promoted.

Scenarios

Route Purpose
GET /scenarios/templates Template ids, titles and parameters with JSON Schema.
POST /plans/{id}/scenarios/{templateId}/preview What the template would do. Stores nothing.
POST /plans/{id}/scenarios/{templateId}/branch Store it as a branch (write scope).
GET /plans/{id}/scenarios/survivor?ages=70,80,90&evaluate=true Survivor scenarios (couples only).

Templates: market-crash, job-loss, career-break, early-retirement, downsizing, child, inheritance, long-term-care, survivor, relocation. An unknown template is 404; bad parameters are 400.

What this does not do

The API never reads or writes a file path from a request. There is no /progress route: use the snapshots routes.

Last checked against the code on .