API reference
Every Glideworth REST API operation by group, with method, path, summary, required key scope, parameters and the request and response schema names.
This page lists every operation in the OpenAPI 3.1 document that the Glideworth server generates from its own route definitions. It is plain HTML, so you can search all of it with your browser’s find command. Conventions that apply to every call (units, errors, pagination, idempotency, concurrency) are on REST API overview and conventions; keys and scopes are on API authentication, scopes and roles.
- Scope is the lowest key scope that may call the operation:
read,simulateorwrite. Awritekey can also read and simulate. Operations marked “no API-key scope” are the browser sign-in routes and the public share-link read. - Headers. Every write accepts an
Idempotency-Keyheader for safe retries. Operations that change a plan or household acceptIf-Matchwith the version from theETagyou read. - Errors. The listed error codes are the ones the document declares; the body is always
{ "error": { "code", "message", "details" } }.
FX rates
Exchange rates for foreign-currency accounts, assets and debts.
-
GET
/api/v1/households/{id}/fx-ratesscope: readFX rates of a household: foreign currency -> base currency (as of the finances date)
listFxRates- Parameters
-
id(path , required, string) - Responses
-
200 Rates
(
FxRates) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/fx-ratesscope: writeAdd or update one pair (upsert by from/to)
setFxRate- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Saved
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/fx-ratesscope: writeReplace all FX rates
replaceFxRates- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Replaced
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/fx-rates/{pair}scope: writeRemove one pair
deleteFxRate- Parameters
-
id(path , required, string) ,pair(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Removed Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Users
Collaboration: invite a partner or adviser, roles, passphrase resets, audit log.
-
GET
/api/v1/audit-logscope: readWho changed what (newest first)
listAuditLog- Parameters
-
userId(query , string) ,resourceType(query , string) ,resourceId(query , string) ,limit(query , integer) ,before(query , integer | null) - Responses
-
200 Entries
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/usersscope: writeList the people who can sign in to this instance
listUsers- Responses
-
200 Users
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/usersscope: writeInvite a partner (editor) or a read-only viewer such as an adviser
inviteUser- Headers
-
idempotency-key - Request body
-
UserInviteRequestapplication/json - Responses
-
201 Invited
(
UserInvite) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/users/{id}scope: writeRename, change the role of, or disable/enable a user
updateUser- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
User) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/users/{id}scope: writeRemove a user (their sessions, API keys and OAuth grants go too; history keeps their name)
deleteUser- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/users/{id}/invitescope: writeIssue a fresh invite token for a user who has not accepted yet
reinviteUser- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Invite
(
UserInvite) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/users/{id}/reset-passphrasescope: writeReset someone’s passphrase: signs them out everywhere and returns a one-time token
resetUserPassphrase- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Reset token
(
UserReset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Share links
Expiring, revocable read-only links to a plan’s results.
Check-ins
Scheduled re-runs, plan health history, notifications.
-
GET
/api/v1/notificationsscope: readNotifications raised by check-ins (newest first)
listNotifications- Parameters
-
unread(query , string) ,planId(query , string) ,since(query , string) ,limit(query , integer) - Responses
-
200 Notifications
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/notifications/readscope: writeMark notifications read (`ids`, or `all`)
markNotificationsRead- Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Marked
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/changes-since-checkinscope: readWhat changed since my last check-in
changesSinceCheckin- Parameters
-
id(path , required, string) ,since(query , string) ,refresh(query , string) - Responses
-
200 Changes
(
ChangesSinceCheckin) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/checkinsscope: writeCheck in on this plan now: re-run projection, chance of success and audit; store the result
runCheckin- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Check-in
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/healthscope: readPlan health history: success rate, FI year and net worth versus plan over time (newest first)
planHealthHistory- Parameters
-
id(path , required, string) ,limit(query , integer) ,since(query , string) - Responses
-
200 History
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/schedulescope: readThe check-in schedule: cadence, thresholds, last and next run
getSchedule- Responses
-
200 Schedule
(
Schedule) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/schedulescope: writeChange the schedule (partial update; null clears intervalHours / monteCarloTrials)
updateSchedule- Headers
-
idempotency-key - Request body
-
SchedulePatchapplication/json - Responses
-
200 Schedule
(
Schedule) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
OAuth
OAuth 2.1 grants and clients for remote MCP clients (the protocol endpoints are under /oauth and /.well-known).
-
GET
/api/v1/me/oauth-grantsscope: readMCP clients you have connected (OAuth)
listMyOAuthGrants- Responses
-
200 Grants
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/me/oauth-grants/{grantId}scope: readDisconnect an MCP client (revokes its tokens; needs a signed-in session or a write key). The owner may disconnect anyone's
revokeMyOAuthGrant- Parameters
-
grantId(path , required, string) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/oauth/clientsscope: writeRegistered OAuth clients (dynamic registration)
listOAuthClients- Parameters
-
limit(query , integer) ,cursor(query , string) - Responses
-
200 Clients
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/oauth/clients/{id}scope: writeRemove an OAuth client and revoke every token it holds
deleteOAuthClient- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Households
Household, people and dependents.
-
GET
/api/v1/householdsscope: readList households
listHouseholds- Parameters
-
limit(query , integer) ,cursor(query , string) - Responses
-
200 Households
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/householdsscope: writeCreate a household with its current finances
createHousehold- Headers
-
idempotency-key - Request body
-
HouseholdCreateapplication/json - Responses
-
201 Created
(
HouseholdRecord) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}scope: readGet a household and its current finances (ETag = version; supports If-None-Match)
getHousehold- Parameters
-
id(path , required, string) - Responses
-
200 Household
(
HouseholdRecord) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}scope: writeReplace the household body (people, dependents, location, currency...), or the whole current-finances document
replaceHousehold- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
CurrentFinancesDocument | Householdapplication/json - Responses
-
200 Updated
(
CurrentFinancesSaved) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}scope: writeMerge-patch household fields
patchHousehold- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
HouseholdRecord) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}scope: writeDelete a household and everything in it (plans, history, snapshots)
deleteHousehold- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/current-financesscope: writeSave the whole current-finances document atomically: people, accounts, real assets and debts
replaceCurrentFinances- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
CurrentFinancesDocumentapplication/json - Responses
-
200 Saved
(
CurrentFinancesSaved) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/reorder/{collection}scope: writePersist the display order of accounts, real assets, debts or plans
reorderHouseholdCollection- Parameters
-
id(path , required, string) ,collection(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
ReorderRequestapplication/json - Responses
-
200 The resulting order of every id
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: residency
Where each person lives over the plan (dated moves, per person or everyone) and the resulting timeline.
-
GET
/api/v1/plans/{id}/cross-border/itemsscope: readAccounts, assets and income whose country differs from where their owner lives at some point
listCrossBorderItems- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/residencyscope: writeReorder the residency changes
reorderResidency- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/residencyscope: readList the plan's residency changes
listResidency- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/residencyscope: writeAdd a residency change
addResidency- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
ResidencyCreateapplication/json - Responses
-
201 Created
(
ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/residency-timelinescope: readEach person's residency over the plan: household location, dated moves and relocation milestones
getResidencyTimeline- Parameters
-
id(path , required, string) - Responses
-
200 Timeline
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/residency/{itemId}scope: readGet a residency change
getResidencyItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/residency/{itemId}scope: writeReplace a residency change
replaceResidencyItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
ResidencyCreateapplication/json - Responses
-
200 Updated
(
ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/residency/{itemId}scope: writePartially update a residency change (JSON Merge Patch)
patchResidencyItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/residency/{itemId}scope: writeRemove a residency change
removeResidencyItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Cross-border rules
Read-only tables the engine uses: non-resident rules, treaties, foreign-wrapper recognition, simplifications.
-
GET
/api/v1/cross-border/countriesscope: readCountries with cross-border data: tax currency, non-resident rule depth, treaties, currency pegs
listCrossBorderCountries- Responses
-
200 Countries
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/cross-border/explainscope: readHow income of one category from one country is taxed for a resident of another, and why (stateless)
explainCrossBorderRule- Headers
-
idempotency-key - Request body
-
ExplainRuleRequestapplication/json - Responses
-
200 Treatment
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/cross-border/non-resident-rules/{country}scope: readHow a country taxes non-residents, per income category, with its wrappers, exit rules and sources
getNonResidentRules- Parameters
-
country(path , required, string) - Responses
-
200 Rules
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/cross-border/simplificationsscope: readKnown simplifications of the cross-border model (general, then per country)
getCrossBorderSimplifications- Parameters
-
countries(query , string) - Responses
-
200 Simplifications
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/cross-border/treatiesscope: readTreaties in the tables (optionally those of one country)
listTreaties- Parameters
-
country(query , string) - Responses
-
200 Treaties
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/cross-border/treaties/{a}/{b}scope: readThe treaty between two countries (or the fallback), with the decision for every income category both ways
getTreaty- Parameters
-
a(path , required, string) ,b(path , required, string) - Responses
-
200 Treaty
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/cross-border/wrappersscope: readHow a residence country treats another country's tax-advantaged accounts
getWrapperRecognition- Parameters
-
residence(query , string) ,accountCountry(query , string) - Responses
-
200 Wrapper recognition
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Accounts
Current-finance accounts and bulk balance updates.
-
GET
/api/v1/households/{id}/accountsscope: readList accounts
listAccounts- Parameters
-
id(path , required, string) ,limit(query , integer) ,cursor(query , string) ,includeArchived(query , boolean | null) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/accountsscope: writeCreate a account
createAccount- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
AccountCreateapplication/json - Responses
-
201 Created
(
Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/accounts/{itemId}scope: readGet a account
getAccount- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/accounts/{itemId}scope: writeReplace a account
replaceAccount- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
AccountCreateapplication/json - Responses
-
200 Updated
(
Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/accounts/{itemId}scope: writeMerge-patch a account (e.g. just its balance)
patchAccount- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/accounts/{itemId}scope: writeDelete a account (409 IN_USE when plans reference it, unless force=true; prefer archived=true)
deleteAccount- Parameters
-
id(path , required, string) ,itemId(path , required, string) ,force(query , boolean | null) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/balancesscope: writeBulk balance update (integration use case: a budgeting tool pushes balances)
updateBalances- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
BalanceUpdateapplication/json - Responses
-
200 Updated
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plans
Plans, versions and lifecycle.
-
GET
/api/v1/plansscope: readList plans
listPlans- Parameters
-
limit(query , integer) ,cursor(query , string) ,householdId(query , Id) ,status(query , string) ,q(query , string) - Responses
-
200 Plans
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plansscope: writeCreate a plan (branches are created with POST /plans/{id}/branches)
createPlan- Headers
-
idempotency-key - Request body
-
PlanCreateapplication/json - Responses
-
201 Created
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}scope: readGet a plan (ETag = version; supports If-None-Match)
getPlan- Parameters
-
id(path , required, string) - Responses
-
200 Plan
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}scope: writeReplace a plan (If-Match required)
replacePlan- Parameters
-
id(path , required, string) - Headers
-
if-match(required) ,idempotency-key - Request body
-
PlanUpdateapplication/json - Responses
-
200 Updated
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}scope: writeEdit a plan with RFC 6902 JSON Patch (address array items by id: /income/[id=salary]/amount/value)
patchPlan- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PatchOp[]application/json - Responses
-
200 Updated
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}scope: writeDelete a plan (409 IN_USE when it has branches, unless force=true, which promotes them)
deletePlan- Parameters
-
id(path , required, string) ,force(query , boolean | null) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/archivescope: writeArchive a plan (kept, hidden from active lists)
archivePlan- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
-
200 Updated plan
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/duplicatescope: writeDuplicate a plan into an independent copy
duplicatePlan- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
201 The copy
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/set-mainscope: writeMake this the main plan (the previous main plan is demoted)
setMainPlan- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
-
200 Updated plan
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/unarchivescope: writeRestore an archived plan
unarchivePlan- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
-
200 Updated plan
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan history
Version history and undo.
-
GET
/api/v1/plans/{id}/versionsscope: readPlan history, newest first (one entry per write, with actor and message)
listPlanVersions- Parameters
-
id(path , required, string) ,limit(query , integer) ,cursor(query , string) - Responses
-
200 Versions
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/versions/{version}scope: readThe full plan body at an earlier version
getPlanVersion- Parameters
-
id(path , required, string) ,version(path , required, integer) - Responses
-
200 Plan as of that version
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/versions/{version}/diffscope: readWhat changed between a version and another version (default: the current plan)
diffPlanVersion- Parameters
-
id(path , required, string) ,version(path , required, integer) ,against(query , string) - Responses
-
200 Diff
(
PlanDiff) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/versions/{version}/restorescope: writeUndo: write an earlier version back as a NEW version (history is never rewritten)
restorePlanVersion- Parameters
-
id(path , required, string) ,version(path , required, integer) - Headers
-
if-match,idempotency-key - Responses
-
200 Restored plan
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Branches
Plan branching: child plans that patch a parent.
-
GET
/api/v1/plans/{id}/branchesscope: readBranches of a plan
listBranches- Parameters
-
id(path , required, string) - Responses
-
200 Branches
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/branchesscope: writeBranch a plan: a child that stores a patch over its parent and follows (or pins) the parent version
createBranch- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
CreateBranchapplication/json - Responses
-
201 The branch (a normal plan with `lineage`)
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/diffscope: simulateDiff a branch against its parent, with before/after outcomes (outcome=true runs two projections)
diffBranchAgainstParent- Parameters
-
id(path , required, string) ,outcome(query , boolean | null) - Responses
-
200 Diff
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/mergescope: writeMerge a branch: into its parent, or promote it to a standalone (optionally main) plan
mergeBranch- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
MergeBranchapplication/json - Responses
-
200 Result
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Change sets
Propose, preview, apply or discard edits (the safe way for agents).
-
GET
/api/v1/change-sets/{id}scope: readGet a change set
getChangeSet- Parameters
-
id(path , required, string) - Responses
-
200 Change set
(
ChangeSetView) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/change-sets/{id}/applyscope: writeApply a proposed change set (atomic; writes a plan version attributed to the caller)
applyChangeSet- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Applied
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/change-sets/{id}/discardscope: writeDiscard a proposed change set
discardChangeSet- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Discarded
(
ChangeSetView) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/change-setsscope: readChange sets proposed for a plan (newest first)
listChangeSets- Parameters
-
id(path , required, string) ,limit(query , integer) ,cursor(query , string) ,status(query , string) - Responses
-
200 Change sets
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/change-setsscope: writePropose edits WITHOUT applying: returns the diff and a before/after simulation summary
proposeChangeSet- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
ProposeChangeSetapplication/json - Responses
-
201 Proposed change set
(
ChangeSetView) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/previewscope: simulateWhat-if: diff + before/after outcome for some edits, storing nothing
previewEdits- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Preview
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Simulation
Deterministic projections, Monte Carlo and historical runs.
-
POST
/api/v1/plans/{id}/historicalscope: simulateHistorical backtest, one trial per start year (async job)
runHistorical- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
HistoricalRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/monte-carloscope: simulateMonte Carlo chance-of-success run (async job)
runMonteCarlo- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
MonteCarloRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/simulatescope: simulateDeterministic projection of a stored plan (whole result, or a compact view of selected years/series)
simulatePlan- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
SimulateRequestapplication/json - Responses
-
200 Projection
(
ProjectionResult | CompactProjection) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/simulatescope: simulateStateless: simulate an arbitrary input without storing anything
simulateStateless- Headers
-
idempotency-key - Request body
-
SimulationInputapplication/json - Responses
-
200 Projection
(
ProjectionResult) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Solvers
Goal-seek solvers (async jobs).
-
POST
/api/v1/plans/{id}/solve/earliest-retirementscope: simulateEarliest retirement date at a target success rate (async job)
solveEarliestRetirement- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
EarliestRetirementRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/solve/goal-seekscope: simulateGeneric goal seek over any plan variable (async job)
solveGoalSeek- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
GoalSeekRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/solve/max-spendingscope: simulateMaximum sustainable spending at a target success rate (async job)
solveMaxSpending- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
MaxSpendingRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/solve/required-portfolioscope: simulateSmallest portfolio (as a scale on invested balances) that reaches a target success rate (async job)
solveRequiredPortfolio- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
RequiredPortfolioRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/solve/required-savingsscope: simulateRequired savings to reach a target success rate (async job)
solveRequiredSavings- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
RequiredSavingsRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/solve/safe-withdrawal-ratescope: simulateHighest constant withdrawal rate that still meets a target success rate over N years (async job)
solveSafeWithdrawalRate- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
SafeWithdrawalRateRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/solve/tax-strategyscope: simulateCompare tax strategies (drawdown order, UK allowance use / lump-sum timing, US bracket filling) or your own candidate patches (async job)
optimiseTaxStrategy- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
TaxStrategyRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Insights
Explain, audit, sensitivity, guardrails, compare, tax.
-
POST
/api/v1/insights/comparescope: simulateCompare plans: outcomes side by side, plus a diff and explanation against the first plan
comparePlans- Headers
-
idempotency-key - Request body
-
CompareRequestapplication/json - Responses
-
200 Comparison
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/insights/sepp-comparisonscope: simulate72(t) SEPP methods side by side (RMD, fixed amortisation, fixed annuitisation)
compareSepp- Headers
-
idempotency-key - Request body
-
SeppComparisonRequestapplication/json - Responses
-
200 Comparison
(
SeppComparison) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/auditscope: simulateAssumption audit: double-counted housing, real/nominal mix-ups, implausible returns, missing flows...
auditPlan- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Findings
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/debt-payoffscope: simulateDebt payoff strategies: minimum payments vs avalanche vs snowball
compareDebtPayoff- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
DebtPayoffRequestapplication/json - Responses
-
200 Comparison
(
DebtPayoffComparison) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/explainscope: simulateWhy did the plan end up here? Findings built from the engine trace and ledger
explainPlan- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
ExplainRequestapplication/json - Responses
-
200 Explanation
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/explain-differencescope: simulateWhy do two plans end differently? Diff, explanation and (optionally) which edit caused how much
explainDifference- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
ExplainDifferenceRequestapplication/json - Responses
-
200 Explanation (or a finished Job)
(
object) ; 202 Accepted (successRate attribution) (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/explain-taxationscope: simulateHow one account, asset, debt or income is taxed in a year, and why
explainItemTaxation- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
ExplainTaxationRequestapplication/json - Responses
-
200 Explanation
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/explain-yearscope: simulateWhere did the money go in one year? Narrative from the ledger: income, outflows, withdrawals, saving
explainYear- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
ExplainYearRequestapplication/json - Responses
-
200 Year narrative
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/explain-yearsscope: simulateYear-by-year narratives for a range of years (every Nth)
explainYears- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
ExplainYearsRequestapplication/json - Responses
-
200 Year narratives
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/guardrailsscope: simulateRisk-based spending guardrails: this year's recommended spending (async job)
evaluateGuardrails- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
GuardrailsRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/guyton-klingerscope: simulateGuyton-Klinger guardrails in money terms: when to cut or raise spending (instant)
guytonKlingerGuardrails- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
GuytonKlingerRequestapplication/json - Responses
-
200 Thresholds and action
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/income-by-tax-ratescope: simulateIncome by tax rate: how much income falls in each marginal-rate band, per year (a heatmap)
incomeByTaxRate- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
IncomeByTaxRateRequestapplication/json - Responses
-
200 Matrix
(
IncomeByTaxRateMatrix) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/sensitivityscope: simulateTornado data: how much returns, inflation, spending, income, retirement date and life expectancy move the outcome
sensitivityAnalysis- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
SensitivityRequestapplication/json - Responses
-
200 Bars sorted by swing, largest first (or a finished Job)
(
object) ; 202 Accepted (successRate) (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/stay-or-movescope: simulateCompare staying with moving country: plan diff, outcome deltas, tax by country and basis, attribution
compareStayOrMove- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
StayOrMoveRequestapplication/json - Responses
-
200 Comparison
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/insights/strategy-matrixscope: simulateStrategies x metrics matrix: lifetime tax, net legacy, chance of success and final net worth per strategy, with per-column scores (a heatmap; async job)
strategyMatrix- Parameters
-
id(path , required, string) ,wait(query , number | null) - Headers
-
idempotency-key - Request body
-
StrategyMatrixRequestapplication/json - Responses
-
200 Finished job (cached or waited)
(
Job) ; 202 Accepted: job queued or running (Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/tax-breakdownscope: simulateTax breakdown per year, by jurisdiction and kind (effective/marginal rates)
taxBreakdown- Parameters
-
id(path , required, string) ,fromYear(query , integer | null) ,toYear(query , integer | null) ,basis(query , ValueBasis) ,detail(query , string) - Responses
-
200 Tax breakdown
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/tax-breakdown/by-countryscope: simulateTax by country and basis (residence, source, citizenship, relief, exit, return), lifetime and per year
taxBreakdownByCountry- Parameters
-
id(path , required, string) ,basis(query , string) ,fromYear(query , integer | null) ,toYear(query , integer | null) - Responses
-
200 Tax by country
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Jobs
Async job status, results, cancellation and SSE.
-
GET
/api/v1/jobsscope: simulateList jobs (newest first)
listJobs- Parameters
-
limit(query , integer) ,cursor(query , string) ,status(query , string) ,planId(query , string) - Responses
-
200 Jobs
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/jobs/{id}scope: simulateJob status and progress (poll this)
getJob- Parameters
-
id(path , required, string) - Responses
-
200 Job
(
Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/jobs/{id}/cancelscope: simulateCancel a queued or running job (worker thread is terminated)
cancelJob- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Job (status=cancelled once stopped)
(
Job) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/jobs/{id}/eventsscope: simulateServer-Sent Events: `status` / `progress` events until the job is terminal
streamJobEvents- Parameters
-
id(path , required, string) - Responses
-
200 text/event-stream
(
string) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/jobs/{id}/resultscope: simulateResult of a finished job (409 JOB_NOT_FINISHED / JOB_FAILED / JOB_CANCELLED otherwise)
getJobResult- Parameters
-
id(path , required, string) ,detail(query , string) ,metrics(query , string) ,percentiles(query , string) ,everyNYears(query , integer) - Responses
-
200 Result (shape depends on job kind)
(
MonteCarloResult | GoalSeekResult | GuardrailsResult | object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Progress
Progress snapshots (actuals over time).
-
GET
/api/v1/households/{id}/snapshotsscope: readList progress snapshots (newest first)
listSnapshots- Parameters
-
id(path , required, string) ,limit(query , integer) ,cursor(query , string) ,from(query , string) ,to(query , string) - Responses
-
200 Snapshots
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/snapshotsscope: writeRecord a progress snapshot with explicit values
createSnapshot- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
SnapshotCreateapplication/json - Responses
-
201 Created
(
ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/snapshots/{snapId}scope: readGet a snapshot
getSnapshot- Parameters
-
id(path , required, string) ,snapId(path , required, string) - Responses
-
200 Snapshot
(
ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/snapshots/{snapId}scope: writeReplace a snapshot
replaceSnapshot- Parameters
-
id(path , required, string) ,snapId(path , required, string) - Headers
-
idempotency-key - Request body
-
SnapshotCreateapplication/json - Responses
-
200 Updated
(
ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/snapshots/{snapId}scope: writeMerge-patch a snapshot (edit values, date or note)
patchSnapshot- Parameters
-
id(path , required, string) ,snapId(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/snapshots/{snapId}scope: writeDelete a snapshot
deleteSnapshot- Parameters
-
id(path , required, string) ,snapId(path , required, string) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/snapshots/bulkscope: writeBulk import (backfill) progress snapshots, atomically
bulkImportSnapshots- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Result
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/snapshots/recordscope: writeRecord a snapshot of the household's CURRENT finances (net worth today)
recordSnapshot- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
201 Created
(
ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Data
Export, import and backup.
-
GET
/api/v1/households/{id}/documentscope: readWhole workspace (household, finances, plans, progress, settings) as a GlideworthDocument
getHouseholdDocument- Parameters
-
id(path , required, string) - Responses
-
200 Document
(
GlideworthDocument) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/exportscope: readFull-data export (backup). Same shape as /document, served as a download; re-import with POST /import
exportHousehold- Parameters
-
id(path , required, string) - Responses
-
200 Document file
(
GlideworthDocument) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/export/progressscope: readProgress history (net worth, assets, liabilities, categories) as JSON or CSV
exportProgressTable- Parameters
-
id(path , required, string) ,format(query , string) - Responses
-
200 Progress table
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/import/bank-filescope: writeOFX / QFX / QIF import: balances and spending. dryRun (the default) previews only
importBankFile- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
BankFileImportRequestapplication/json - Responses
-
200 Preview or result
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/import/csvscope: writeCSV import: account balances, progress/net-worth history or transactions. dryRun (the default) previews only
importCsv- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
CsvImportRequestapplication/json - Responses
-
200 Preview or result
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/import/csv/analyzescope: writeDetect the delimiter, bank preset, columns, date and number formats of a CSV (writes nothing)
analyzeCsv- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
CsvAnalyzeRequestapplication/json - Responses
-
200 Analysis with a sample of rows
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/importscope: writeImport a Glideworth export or a ProjectionLab export (dryRun=true returns issues and stats only)
importDocument- Headers
-
idempotency-key - Request body
-
ImportRequestapplication/json - Responses
-
200 Import report
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/export/tables/{table}scope: readA projection table as JSON or CSV (year-by-year, cash-flow, taxes, account-balances)
exportProjectionTable- Parameters
-
id(path , required, string) ,table(path , required, string) ,basis(query , string) ,format(query , string) - Responses
-
200 Table
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/reportscope: readPrintable report as plain data: key figures, milestones, series, year table, finances, assumptions, caveats
planReportData- Parameters
-
id(path , required, string) ,basis(query , string) ,tableEvery(query , integer) ,title(query , string) - Responses
-
200 Report data
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Settings
User settings.
-
GET
/api/v1/settingsscope: readUser settings
getSettings- Responses
-
200 Settings
(
UserSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/settingsscope: writeReplace settings
replaceSettings- Headers
-
idempotency-key - Request body
-
UserSettingsapplication/json - Responses
-
200 Settings
(
UserSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/settingsscope: writeMerge-patch settings
patchSettings- Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Settings
(
UserSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Keys
API key management.
-
GET
/api/v1/keysscope: writeList API keys (metadata only; secrets are never retrievable)
listApiKeys- Parameters
-
limit(query , integer) ,cursor(query , string) - Responses
-
200 Keys
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/keysscope: writeCreate an API key. The secret is returned once. Scopes: read, simulate, write
createApiKey- Headers
-
idempotency-key - Request body
-
ApiKeyCreateapplication/json - Responses
-
201 Created
(
ApiKeyCreated) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/keys/{id}scope: writeRevoke an API key (409 if it is the last active write key). Editors can revoke only their own
revokeApiKey- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Revoked key
(
ApiKeyInfo) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/mescope: simulateWho am I? The credential, the person behind it, their role and effective scopes
whoAmI- Responses
-
200 Principal
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/me/keysscope: readYour own API keys (any role)
listMyApiKeys- Responses
-
200 Keys
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/me/keysscope: readCreate an API key for yourself; scopes are capped by your role (a viewer gets read/simulate only)
createMyApiKey- Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
201 Created
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/me/keys/{id}scope: readRevoke one of your own API keys (needs a signed-in session or a write key)
revokeMyApiKey- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
-
200 Revoked
(
ApiKeyInfo) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Webhooks
Signed event webhooks.
-
GET
/api/v1/webhooksscope: writeList webhook subscriptions
listWebhooks- Responses
-
200 Webhooks
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/webhooksscope: writeSubscribe to events. The signing secret is returned once
createWebhook- Headers
-
idempotency-key - Request body
-
WebhookCreateapplication/json - Responses
-
201 Created
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/webhooks/{id}scope: writeGet a webhook
getWebhook- Parameters
-
id(path , required, string) - Responses
-
200 Webhook
(
Webhook) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/webhooks/{id}scope: writeUpdate url, events, description or active flag
updateWebhook- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Webhook) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/webhooks/{id}scope: writeDelete a webhook
deleteWebhook- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/webhooks/{id}/deliveriesscope: writeRecent deliveries (status, attempts, last error)
listWebhookDeliveries- Parameters
-
id(path , required, string) - Responses
-
200 Deliveries
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/webhooks/{id}/pingscope: writeSend a webhook.ping test delivery
pingWebhook- Parameters
-
id(path , required, string) - Headers
-
idempotency-key - Responses
- 202 Queued Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Scenarios
What-if templates and survivor scenarios, as previews or branches.
-
POST
/api/v1/plans/{id}/scenarios/{templateId}/branchscope: writeInstantiate a what-if template as a BRANCH of the plan (the parent is untouched)
createScenarioBranch- Parameters
-
id(path , required, string) ,templateId(path , required, string) - Headers
-
idempotency-key - Request body
-
ScenarioBranchRequestapplication/json - Responses
-
201 The new branch plan
(
Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/scenarios/{templateId}/previewscope: simulateWhat would this template do to the plan? Ops, readable changes and before/after outcome. Stores nothing
previewScenario- Parameters
-
id(path , required, string) ,templateId(path , required, string) - Headers
-
idempotency-key - Request body
-
ScenarioPreviewRequestapplication/json - Responses
-
200 Preview
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/scenarios/survivorscope: simulateSurvivor scenarios: what if one partner dies at 70 / 80 / 90? (couples only)
survivorScenarios- Parameters
-
id(path , required, string) ,ages(query , string) ,evaluate(query , boolean | null) - Responses
-
200 Scenarios (with outcomes when evaluate=true)
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/scenarios/templatesscope: simulateWhat-if templates (market crash, job loss, retire earlier, survivor...) and their parameters
listScenarioTemplates- Responses
-
200 Templates
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Auth
Browser sign-in: first-run setup, login, logout (session cookie + CSRF token).
-
POST
/api/v1/auth/acceptno API-key scopeAccept an invite or a passphrase reset: choose a passphrase and sign in
authAccept- Request body
-
AuthAcceptapplication/json - Responses
-
200 Passphrase set; session cookies issued
(
AuthSession) Errors: 400, 401, 403, 409, 429.
-
POST
/api/v1/auth/change-passphraseno API-key scopeChange your own passphrase. Signs out all your other sessions
authChangePassphrase- Request body
-
AuthChangePassphraseapplication/json - Responses
-
200 Changed; a fresh session was issued
(
AuthSession) Errors: 400, 401, 403, 409, 429.
-
POST
/api/v1/auth/loginno API-key scopeLog in with the passphrase. Sets an httpOnly, SameSite=Strict session cookie
authLogin- Request body
-
AuthLoginapplication/json - Responses
-
200 Signed in
(
AuthSession) Errors: 400, 401, 403, 409, 429.
-
POST
/api/v1/auth/logoutno API-key scopeEnd the session and clear the cookies (needs X-CSRF-Token)
authLogout- Responses
- 204 Signed out Errors: 403.
-
POST
/api/v1/auth/logout-allno API-key scopeSign out everywhere (every session of the signed-in user, including this one)
authLogoutAll- Responses
- 204 Signed out Errors: 401, 403.
-
POST
/api/v1/auth/setupno API-key scopeFirst run: set the passphrase and sign in. Only works while no passphrase exists
authSetup- Request body
-
AuthSetupapplication/json - Responses
-
201 Passphrase set; session cookies issued
(
AuthSession) Errors: 400, 401, 403, 409, 429.
-
GET
/api/v1/auth/statusno API-key scopeWho am I, and is first-run setup needed? Public
authStatus- Responses
-
200 Status
(
AuthStatus)
Debts
-
GET
/api/v1/households/{id}/debtsscope: readList debts
listDebts- Parameters
-
id(path , required, string) ,limit(query , integer) ,cursor(query , string) ,includeArchived(query , boolean | null) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/debtsscope: writeCreate a debt
createDebt- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
DebtCreateapplication/json - Responses
-
201 Created
(
Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/debts/{itemId}scope: readGet a debt
getDebt- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/debts/{itemId}scope: writeReplace a debt
replaceDebt- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
DebtCreateapplication/json - Responses
-
200 Updated
(
Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/debts/{itemId}scope: writeMerge-patch a debt (e.g. just its balance)
patchDebt- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/debts/{itemId}scope: writeDelete a debt (409 IN_USE when plans reference it, unless force=true; prefer archived=true)
deleteDebt- Parameters
-
id(path , required, string) ,itemId(path , required, string) ,force(query , boolean | null) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
People
-
GET
/api/v1/households/{id}/dependentsscope: readList dependents
listDependents- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/dependentsscope: writeAdd a dependent
addDependent- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
DependentCreateapplication/json - Responses
-
201 Created
(
Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/dependents/{dependentId}scope: readGet a dependent
getDependent- Parameters
-
id(path , required, string) ,dependentId(path , required, string) - Responses
-
200 Item
(
Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/dependents/{dependentId}scope: writeReplace a dependent
replaceDependent- Parameters
-
id(path , required, string) ,dependentId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
DependentCreateapplication/json - Responses
-
200 Updated
(
Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/dependents/{dependentId}scope: writeMerge-patch a dependent
patchDependent- Parameters
-
id(path , required, string) ,dependentId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/dependents/{dependentId}scope: writeRemove a dependent
removeDependent- Parameters
-
id(path , required, string) ,dependentId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/peoplescope: readList people
listPeople- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/peoplescope: writeAdd a person (adding a second person switches the household to couple mode)
addPerson- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PersonCreateapplication/json - Responses
-
201 Created
(
Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/people/{personId}scope: readGet a person
getPerson- Parameters
-
id(path , required, string) ,personId(path , required, string) - Responses
-
200 Item
(
Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/people/{personId}scope: writeReplace a person
replacePerson- Parameters
-
id(path , required, string) ,personId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PersonCreateapplication/json - Responses
-
200 Updated
(
Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/people/{personId}scope: writeMerge-patch a person
patchPerson- Parameters
-
id(path , required, string) ,personId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/people/{personId}scope: writeRemove a person
removePerson- Parameters
-
id(path , required, string) ,personId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/people/{personId}/cross-borderscope: readA person's citizenships, US green card, residence before the plan and state-pension records
getPersonCrossBorder- Parameters
-
id(path , required, string) ,personId(path , required, string) - Responses
-
200 Profile
(
PersonCrossBorder) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/people/{personId}/cross-borderscope: writeReplace a person's cross-border profile (absent fields are removed)
setPersonCrossBorder- Parameters
-
id(path , required, string) ,personId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PersonCrossBorderapplication/json - Responses
-
200 Saved profile and the household version
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/people/{personId}/cross-borderscope: writeUpdate some of a person's cross-border fields (the others are kept)
patchPersonCrossBorder- Parameters
-
id(path , required, string) ,personId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PersonCrossBorderapplication/json - Responses
-
200 Saved profile and the household version
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: expenses
-
GET
/api/v1/plans/{id}/expensesscope: readList the plan's expense events
listExpenses- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/expensesscope: writeAdd a expense event
addExpenses- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
ExpensesCreateapplication/json - Responses
-
201 Created
(
ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/expenses/{itemId}scope: readGet a expense event
getExpensesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/expenses/{itemId}scope: writeReplace a expense event
replaceExpensesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
ExpensesCreateapplication/json - Responses
-
200 Updated
(
ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/expenses/{itemId}scope: writePartially update a expense event (JSON Merge Patch)
patchExpensesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/expenses/{itemId}scope: writeRemove a expense event
removeExpensesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/expensesscope: writeReorder the expense events
reorderExpenses- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: flows
-
GET
/api/v1/plans/{id}/flowsscope: readList the plan's flows
listFlows- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/flowsscope: writeAdd a flow
addFlows- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
FlowsCreateapplication/json - Responses
-
201 Created
(
Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/flows/{itemId}scope: readGet a flow
getFlowsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/flows/{itemId}scope: writeReplace a flow
replaceFlowsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
FlowsCreateapplication/json - Responses
-
200 Updated
(
Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/flows/{itemId}scope: writePartially update a flow (JSON Merge Patch)
patchFlowsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/flows/{itemId}scope: writeRemove a flow
removeFlowsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/flowsscope: writeReorder the flows (the order is the funding priority)
reorderFlows- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: income
-
GET
/api/v1/plans/{id}/incomescope: readList the plan's income events
listIncome- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/incomescope: writeAdd a income event
addIncome- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
IncomeCreateapplication/json - Responses
-
201 Created
(
IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/income/{itemId}scope: readGet a income event
getIncomeItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/income/{itemId}scope: writeReplace a income event
replaceIncomeItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
IncomeCreateapplication/json - Responses
-
200 Updated
(
IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/income/{itemId}scope: writePartially update a income event (JSON Merge Patch)
patchIncomeItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/income/{itemId}scope: writeRemove a income event
removeIncomeItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/incomescope: writeReorder the income events
reorderIncome- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: milestones
-
GET
/api/v1/plans/{id}/milestonesscope: readList the plan's milestones
listMilestones- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/milestonesscope: writeAdd a milestone
addMilestones- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
MilestonesCreateapplication/json - Responses
-
201 Created
(
Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/milestones/{itemId}scope: readGet a milestone
getMilestonesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/milestones/{itemId}scope: writeReplace a milestone
replaceMilestonesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
MilestonesCreateapplication/json - Responses
-
200 Updated
(
Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/milestones/{itemId}scope: writePartially update a milestone (JSON Merge Patch)
patchMilestonesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/milestones/{itemId}scope: writeRemove a milestone
removeMilestonesItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/milestonesscope: writeReorder the milestones
reorderMilestones- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: planned accounts
-
GET
/api/v1/plans/{id}/planned-accountsscope: readList the plan's planned accounts
listPlannedAccounts- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/planned-accountsscope: writeAdd a planned account
addPlannedAccounts- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
PlannedAccountsCreateapplication/json - Responses
-
201 Created
(
PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/planned-accounts/{itemId}scope: readGet a planned account
getPlannedAccountsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/planned-accounts/{itemId}scope: writeReplace a planned account
replacePlannedAccountsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PlannedAccountsCreateapplication/json - Responses
-
200 Updated
(
PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/planned-accounts/{itemId}scope: writePartially update a planned account (JSON Merge Patch)
patchPlannedAccountsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/planned-accounts/{itemId}scope: writeRemove a planned account
removePlannedAccountsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/planned-accountsscope: writeReorder the planned accounts
reorderPlannedAccounts- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: planned assets
-
GET
/api/v1/plans/{id}/planned-real-assetsscope: readList the plan's planned real assets
listPlannedRealAssets- Parameters
-
id(path , required, string) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/plans/{id}/planned-real-assetsscope: writeAdd a planned real asset
addPlannedRealAssets- Parameters
-
id(path , required, string) ,index(query , integer | null) - Headers
-
if-match,idempotency-key - Request body
-
PlannedRealAssetsCreateapplication/json - Responses
-
201 Created
(
PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/planned-real-assets/{itemId}scope: readGet a planned real asset
getPlannedRealAssetsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/planned-real-assets/{itemId}scope: writeReplace a planned real asset
replacePlannedRealAssetsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
PlannedRealAssetsCreateapplication/json - Responses
-
200 Updated
(
PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/planned-real-assets/{itemId}scope: writePartially update a planned real asset (JSON Merge Patch)
patchPlannedRealAssetsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/planned-real-assets/{itemId}scope: writeRemove a planned real asset
removePlannedRealAssetsItem- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/reorder/planned-real-assetsscope: writeReorder the planned real assets
reorderPlannedRealAssets- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Reordered
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Plan: settings
-
GET
/api/v1/plans/{id}/assumptionsscope: readGet the plan's assumptions
getAssumptions- Parameters
-
id(path , required, string) - Responses
-
200 assumptions
(
Assumptions) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/assumptionsscope: writeReplace the plan's assumptions
setAssumptions- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
Assumptionsapplication/json - Responses
-
200 Updated
(
Assumptions) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/assumptionsscope: writePartially update the plan's assumptions (JSON Merge Patch)
patchAssumptions- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
Assumptions) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/assumptionsscope: writeReset the plan's assumptions to defaults
resetAssumptions- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/drawdownscope: readGet the plan's drawdown settings
getDrawdown- Parameters
-
id(path , required, string) - Responses
-
200 drawdown settings
(
DrawdownSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/drawdownscope: writeReplace the plan's drawdown settings
setDrawdown- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
DrawdownSettingsapplication/json - Responses
-
200 Updated
(
DrawdownSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/drawdownscope: writePartially update the plan's drawdown settings (JSON Merge Patch)
patchDrawdown- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
DrawdownSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/drawdownscope: writeReset the plan's drawdown settings to defaults
resetDrawdown- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/flex-spendingscope: readGet the plan's flexible spending
getFlexSpending- Parameters
-
id(path , required, string) - Responses
-
200 flexible spending
(
FlexSpending) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/flex-spendingscope: writeReplace the plan's flexible spending
setFlexSpending- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
FlexSpendingapplication/json - Responses
-
200 Updated
(
FlexSpending) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/flex-spendingscope: writePartially update the plan's flexible spending (JSON Merge Patch)
patchFlexSpending- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
FlexSpending) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/flex-spendingscope: writeReset the plan's flexible spending to defaults
resetFlexSpending- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/leftoverscope: readGet the plan's leftover policy
getLeftover- Parameters
-
id(path , required, string) - Responses
-
200 leftover policy
(
LeftoverPolicy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/leftoverscope: writeReplace the plan's leftover policy
setLeftover- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
LeftoverPolicyapplication/json - Responses
-
200 Updated
(
LeftoverPolicy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/leftoverscope: writePartially update the plan's leftover policy (JSON Merge Patch)
patchLeftover- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
LeftoverPolicy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/leftoverscope: writeReset the plan's leftover policy to defaults
resetLeftover- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/monte-carlo-settingsscope: readGet the plan's Monte Carlo settings
getMonteCarlo- Parameters
-
id(path , required, string) - Responses
-
200 Monte Carlo settings
(
MonteCarloSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/monte-carlo-settingsscope: writeReplace the plan's Monte Carlo settings
setMonteCarlo- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
MonteCarloSettingsapplication/json - Responses
-
200 Updated
(
MonteCarloSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/monte-carlo-settingsscope: writePartially update the plan's Monte Carlo settings (JSON Merge Patch)
patchMonteCarlo- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
MonteCarloSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/monte-carlo-settingsscope: writeReset the plan's Monte Carlo settings to defaults
resetMonteCarlo- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/risk-guardrailsscope: readGet the plan's risk guardrails
getRiskGuardrails- Parameters
-
id(path , required, string) - Responses
-
200 risk guardrails
(
RiskGuardrails) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/risk-guardrailsscope: writeReplace the plan's risk guardrails
setRiskGuardrails- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
RiskGuardrailsapplication/json - Responses
-
200 Updated
(
RiskGuardrails) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/risk-guardrailsscope: writePartially update the plan's risk guardrails (JSON Merge Patch)
patchRiskGuardrails- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
RiskGuardrails) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/risk-guardrailsscope: writeRemove the plan's risk guardrails
removeRiskGuardrails- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/tax-settingsscope: readGet the plan's tax settings
getTax- Parameters
-
id(path , required, string) - Responses
-
200 tax settings
(
TaxConfig) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/tax-settingsscope: writeReplace the plan's tax settings
setTax- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
TaxConfigapplication/json - Responses
-
200 Updated
(
TaxConfig) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/tax-settingsscope: writePartially update the plan's tax settings (JSON Merge Patch)
patchTax- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
TaxConfig) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/tax-settingsscope: writeReset the plan's tax settings to defaults
resetTax- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/tax-strategyscope: readGet the plan's tax strategy
getTaxStrategy- Parameters
-
id(path , required, string) - Responses
-
200 tax strategy
(
TaxStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/tax-strategyscope: writeReplace the plan's tax strategy
setTaxStrategy- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
TaxStrategyapplication/json - Responses
-
200 Updated
(
TaxStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/tax-strategyscope: writePartially update the plan's tax strategy (JSON Merge Patch)
patchTaxStrategy- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
TaxStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/tax-strategyscope: writeRemove the plan's tax strategy
removeTaxStrategy- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/plans/{id}/withdrawal-strategyscope: readGet the plan's withdrawal strategy
getWithdrawalStrategy- Parameters
-
id(path , required, string) - Responses
-
200 withdrawal strategy
(
WithdrawalStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/plans/{id}/withdrawal-strategyscope: writeReplace the plan's withdrawal strategy
setWithdrawalStrategy- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
WithdrawalStrategyapplication/json - Responses
-
200 Updated
(
WithdrawalStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/plans/{id}/withdrawal-strategyscope: writePartially update the plan's withdrawal strategy (JSON Merge Patch)
patchWithdrawalStrategy- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
WithdrawalStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/plans/{id}/withdrawal-strategyscope: writeRemove the plan's withdrawal strategy
removeWithdrawalStrategy- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Real assets
-
GET
/api/v1/households/{id}/real-assetsscope: readList real assets
listRealAssets- Parameters
-
id(path , required, string) ,limit(query , integer) ,cursor(query , string) ,includeArchived(query , boolean | null) - Responses
-
200 Items
(
object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
POST
/api/v1/households/{id}/real-assetsscope: writeCreate a real asset
createRealAsset- Parameters
-
id(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
RealAssetCreateapplication/json - Responses
-
201 Created
(
RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
GET
/api/v1/households/{id}/real-assets/{itemId}scope: readGet a real asset
getRealAsset- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Responses
-
200 Item
(
RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PUT
/api/v1/households/{id}/real-assets/{itemId}scope: writeReplace a real asset
replaceRealAsset- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
RealAssetCreateapplication/json - Responses
-
200 Updated
(
RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
PATCH
/api/v1/households/{id}/real-assets/{itemId}scope: writeMerge-patch a real asset (e.g. just its balance)
patchRealAsset- Parameters
-
id(path , required, string) ,itemId(path , required, string) - Headers
-
if-match,idempotency-key - Request body
-
objectapplication/json - Responses
-
200 Updated
(
RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
-
DELETE
/api/v1/households/{id}/real-assets/{itemId}scope: writeDelete a real asset (409 IN_USE when plans reference it, unless force=true; prefer archived=true)
deleteRealAsset- Parameters
-
id(path , required, string) ,itemId(path , required, string) ,force(query , boolean | null) - Headers
-
if-match,idempotency-key - Responses
- 204 Deleted Errors: 400, 401, 403, 404, 409, 422, 429, 501.
Last checked against the code on .