API and MCP

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, simulate or write. A write key 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-Key header for safe retries. Operations that change a plan or household accept If-Match with the version from the ETag you read.
  • Errors. The listed error codes are the ones the document declares; the body is always { "error": { "code", "message", "details" } }.

Glideworth API 1.0.0, OpenAPI 3.1.0: 265 operations in34 groups. 257 need an API key with a stated scope; 8 are the browser sign-in and share-link routes.

FX rates

Exchange rates for foreign-currency accounts, assets and debts.

  • GET/api/v1/households/{id}/fx-ratesscope: read

    FX 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: write

    Add or update one pair (upsert by from/to) setFxRate

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Saved (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PUT/api/v1/households/{id}/fx-ratesscope: write

    Replace all FX rates replaceFxRates

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Replaced (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/fx-rates/{pair}scope: write

    Remove 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: read

    Who 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: write

    List 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: write

    Invite a partner (editor) or a read-only viewer such as an adviser inviteUser

    Headers
    idempotency-key
    Request body
    UserInviteRequest application/json
    Responses
    201 Invited (UserInvite) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/users/{id}scope: write

    Rename, change the role of, or disable/enable a user updateUser

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (User) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/users/{id}scope: write

    Remove 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: write

    Issue 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: write

    Reset 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.

Expiring, revocable read-only links to a plan’s results.

  • GET/api/v1/shared/{token}no API-key scope

    Public: the results behind a share link. No sign-in getSharedPlan

    Parameters
    token (path, required, string)
    Responses
    200 The shared results (SharedPlan) Errors: 400, 404, 429.

Check-ins

Scheduled re-runs, plan health history, notifications.

  • GET/api/v1/notificationsscope: read

    Notifications 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: write

    Mark notifications read (`ids`, or `all`) markNotificationsRead

    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    200 Marked (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/changes-since-checkinscope: read

    What 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: write

    Check 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: read

    Plan 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: read

    The 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: write

    Change the schedule (partial update; null clears intervalHours / monteCarloTrials) updateSchedule

    Headers
    idempotency-key
    Request body
    SchedulePatch application/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: read

    MCP 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: read

    Disconnect an MCP client (revokes its tokens) 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: write

    Registered 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: write

    Remove 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: read

    List 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: write

    Create a household with its current finances createHousehold

    Headers
    idempotency-key
    Request body
    HouseholdCreate application/json
    Responses
    201 Created (HouseholdRecord) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}scope: read

    Get 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: write

    Replace 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 | Household application/json
    Responses
    200 Updated (CurrentFinancesSaved) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}scope: write

    Merge-patch household fields patchHousehold

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (HouseholdRecord) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}scope: write

    Delete 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: write

    Save 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
    CurrentFinancesDocument application/json
    Responses
    200 Saved (CurrentFinancesSaved) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PUT/api/v1/households/{id}/reorder/{collection}scope: write

    Persist 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
    ReorderRequest application/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: read

    Accounts, 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: write

    Reorder the residency changes reorderResidency

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Reordered (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/residencyscope: read

    List 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: write

    Add a residency change addResidency

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    ResidencyCreate application/json
    Responses
    201 Created (ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/residency-timelinescope: read

    Each 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: read

    Get 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: write

    Replace a residency change replaceResidencyItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    ResidencyCreate application/json
    Responses
    200 Updated (ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/residency/{itemId}scope: write

    Partially update a residency change (JSON Merge Patch) patchResidencyItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (ResidencyChange) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/residency/{itemId}scope: write

    Remove 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: read

    Countries 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: read

    How income of one category from one country is taxed for a resident of another, and why (stateless) explainCrossBorderRule

    Headers
    idempotency-key
    Request body
    ExplainRuleRequest application/json
    Responses
    200 Treatment (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/cross-border/non-resident-rules/{country}scope: read

    How 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: read

    Known 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: read

    Treaties 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: read

    The 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: read

    How 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: read

    List 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: write

    Create a account createAccount

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    AccountCreate application/json
    Responses
    201 Created (Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}/accounts/{itemId}scope: read

    Get 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: write

    Replace a account replaceAccount

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    AccountCreate application/json
    Responses
    200 Updated (Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}/accounts/{itemId}scope: write

    Merge-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
    object application/json
    Responses
    200 Updated (Account) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/accounts/{itemId}scope: write

    Delete 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: write

    Bulk balance update (integration use case: a budgeting tool pushes balances) updateBalances

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    BalanceUpdate application/json
    Responses
    200 Updated (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Plans

Plans, versions and lifecycle.

  • GET/api/v1/plansscope: read

    List 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: write

    Create a plan (branches are created with POST /plans/{id}/branches) createPlan

    Headers
    idempotency-key
    Request body
    PlanCreate application/json
    Responses
    201 Created (Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}scope: read

    Get 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: write

    Replace a plan (If-Match required) replacePlan

    Parameters
    id (path, required, string)
    Headers
    if-match (required), idempotency-key
    Request body
    PlanUpdate application/json
    Responses
    200 Updated (Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}scope: write

    Edit 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: write

    Delete 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: write

    Archive 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: write

    Duplicate a plan into an independent copy duplicatePlan

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    201 The copy (Plan) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/set-mainscope: write

    Make 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: write

    Restore 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: read

    Plan 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: read

    The 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: read

    What 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: write

    Undo: 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: read

    Branches 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: write

    Branch 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
    CreateBranch application/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: simulate

    Diff 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: write

    Merge 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
    MergeBranch application/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: read

    Get 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: write

    Apply 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: write

    Discard 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: read

    Change 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: write

    Propose edits WITHOUT applying: returns the diff and a before/after simulation summary proposeChangeSet

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    ProposeChangeSet application/json
    Responses
    201 Proposed change set (ChangeSetView) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/previewscope: simulate

    What-if: diff + before/after outcome for some edits, storing nothing previewEdits

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/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: simulate

    Historical backtest, one trial per start year (async job) runHistorical

    Parameters
    id (path, required, string), wait (query, number | null)
    Headers
    idempotency-key
    Request body
    HistoricalRequest application/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: simulate

    Monte Carlo chance-of-success run (async job) runMonteCarlo

    Parameters
    id (path, required, string), wait (query, number | null)
    Headers
    idempotency-key
    Request body
    MonteCarloRequest application/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: simulate

    Deterministic 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
    SimulateRequest application/json
    Responses
    200 Projection (ProjectionResult | CompactProjection) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/simulatescope: simulate

    Stateless: simulate an arbitrary input without storing anything simulateStateless

    Headers
    idempotency-key
    Request body
    SimulationInput application/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: simulate

    Earliest retirement date at a target success rate (async job) solveEarliestRetirement

    Parameters
    id (path, required, string), wait (query, number | null)
    Headers
    idempotency-key
    Request body
    EarliestRetirementRequest application/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: simulate

    Generic goal seek over any plan variable (async job) solveGoalSeek

    Parameters
    id (path, required, string), wait (query, number | null)
    Headers
    idempotency-key
    Request body
    GoalSeekRequest application/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: simulate

    Maximum sustainable spending at a target success rate (async job) solveMaxSpending

    Parameters
    id (path, required, string), wait (query, number | null)
    Headers
    idempotency-key
    Request body
    MaxSpendingRequest application/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: simulate

    Smallest 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
    RequiredPortfolioRequest application/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: simulate

    Required savings to reach a target success rate (async job) solveRequiredSavings

    Parameters
    id (path, required, string), wait (query, number | null)
    Headers
    idempotency-key
    Request body
    RequiredSavingsRequest application/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: simulate

    Highest 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
    SafeWithdrawalRateRequest application/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: simulate

    Compare 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
    TaxStrategyRequest application/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: simulate

    Compare plans: outcomes side by side, plus a diff and explanation against the first plan comparePlans

    Headers
    idempotency-key
    Request body
    CompareRequest application/json
    Responses
    200 Comparison (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/insights/sepp-comparisonscope: simulate

    72(t) SEPP methods side by side (RMD, fixed amortisation, fixed annuitisation) compareSepp

    Headers
    idempotency-key
    Request body
    SeppComparisonRequest application/json
    Responses
    200 Comparison (SeppComparison) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/auditscope: simulate

    Assumption 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: simulate

    Debt payoff strategies: minimum payments vs avalanche vs snowball compareDebtPayoff

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    DebtPayoffRequest application/json
    Responses
    200 Comparison (DebtPayoffComparison) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/explainscope: simulate

    Why 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
    ExplainRequest application/json
    Responses
    200 Explanation (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/explain-differencescope: simulate

    Why 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
    ExplainDifferenceRequest application/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: simulate

    How one account, asset, debt or income is taxed in a year, and why explainItemTaxation

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    ExplainTaxationRequest application/json
    Responses
    200 Explanation (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/explain-yearscope: simulate

    Where 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
    ExplainYearRequest application/json
    Responses
    200 Year narrative (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/explain-yearsscope: simulate

    Year-by-year narratives for a range of years (every Nth) explainYears

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    ExplainYearsRequest application/json
    Responses
    200 Year narratives (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/guardrailsscope: simulate

    Risk-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
    GuardrailsRequest application/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: simulate

    Guyton-Klinger guardrails in money terms: when to cut or raise spending (instant) guytonKlingerGuardrails

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    GuytonKlingerRequest application/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: simulate

    Income 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
    IncomeByTaxRateRequest application/json
    Responses
    200 Matrix (IncomeByTaxRateMatrix) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/sensitivityscope: simulate

    Tornado 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
    SensitivityRequest application/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: simulate

    Compare 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
    StayOrMoveRequest application/json
    Responses
    200 Comparison (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/plans/{id}/insights/strategy-matrixscope: simulate

    Strategies 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
    StrategyMatrixRequest application/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: simulate

    Tax 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: simulate

    Tax 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: simulate

    List 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: simulate

    Job 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: simulate

    Cancel 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: simulate

    Server-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: simulate

    Result 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: read

    List 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: write

    Record a progress snapshot with explicit values createSnapshot

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    SnapshotCreate application/json
    Responses
    201 Created (ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}/snapshots/{snapId}scope: read

    Get 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: write

    Replace a snapshot replaceSnapshot

    Parameters
    id (path, required, string), snapId (path, required, string)
    Headers
    idempotency-key
    Request body
    SnapshotCreate application/json
    Responses
    200 Updated (ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}/snapshots/{snapId}scope: write

    Merge-patch a snapshot (edit values, date or note) patchSnapshot

    Parameters
    id (path, required, string), snapId (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (ProgressSnapshot) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/snapshots/{snapId}scope: write

    Delete 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: write

    Bulk import (backfill) progress snapshots, atomically bulkImportSnapshots

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    200 Result (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/households/{id}/snapshots/recordscope: write

    Record a snapshot of the household's CURRENT finances (net worth today) recordSnapshot

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/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: read

    Whole 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: read

    Full-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: read

    Progress 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: write

    OFX / QFX / QIF import: balances and spending. dryRun (the default) previews only importBankFile

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    BankFileImportRequest application/json
    Responses
    200 Preview or result (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/households/{id}/import/csvscope: write

    CSV 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
    CsvImportRequest application/json
    Responses
    200 Preview or result (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/households/{id}/import/csv/analyzescope: write

    Detect 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
    CsvAnalyzeRequest application/json
    Responses
    200 Analysis with a sample of rows (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/importscope: write

    Import a Glideworth export or a ProjectionLab export (dryRun=true returns issues and stats only) importDocument

    Headers
    idempotency-key
    Request body
    ImportRequest application/json
    Responses
    200 Import report (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/export/tables/{table}scope: read

    A 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: read

    Printable 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: read

    User settings getSettings

    Responses
    200 Settings (UserSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PUT/api/v1/settingsscope: write

    Replace settings replaceSettings

    Headers
    idempotency-key
    Request body
    UserSettings application/json
    Responses
    200 Settings (UserSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/settingsscope: write

    Merge-patch settings patchSettings

    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    200 Settings (UserSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Keys

API key management.

  • GET/api/v1/keysscope: write

    List 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: write

    Create an API key. The secret is returned once. Scopes: read, simulate, write createApiKey

    Headers
    idempotency-key
    Request body
    ApiKeyCreate application/json
    Responses
    201 Created (ApiKeyCreated) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/keys/{id}scope: write

    Revoke 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: simulate

    Who 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: read

    Your own API keys (any role) listMyApiKeys

    Responses
    200 Keys (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/me/keysscope: read

    Create an API key for yourself; scopes are capped by your role (a viewer gets read/simulate only) createMyApiKey

    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    201 Created (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/me/keys/{id}scope: read

    Revoke 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: write

    List webhook subscriptions listWebhooks

    Responses
    200 Webhooks (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • POST/api/v1/webhooksscope: write

    Subscribe to events. The signing secret is returned once createWebhook

    Headers
    idempotency-key
    Request body
    WebhookCreate application/json
    Responses
    201 Created (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/webhooks/{id}scope: write

    Get 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: write

    Update url, events, description or active flag updateWebhook

    Parameters
    id (path, required, string)
    Headers
    idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (Webhook) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/webhooks/{id}scope: write

    Delete 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: write

    Recent 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: write

    Send 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: write

    Instantiate 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
    ScenarioBranchRequest application/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: simulate

    What 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
    ScenarioPreviewRequest application/json
    Responses
    200 Preview (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/scenarios/survivorscope: simulate

    Survivor 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: simulate

    What-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 scope

    Accept an invite or a passphrase reset: choose a passphrase and sign in authAccept

    Request body
    AuthAccept application/json
    Responses
    200 Passphrase set; session cookies issued (AuthSession) Errors: 400, 401, 403, 409, 429.
  • POST/api/v1/auth/change-passphraseno API-key scope

    Change your own passphrase. Signs out all your other sessions authChangePassphrase

    Request body
    AuthChangePassphrase application/json
    Responses
    200 Changed; a fresh session was issued (AuthSession) Errors: 400, 401, 403, 409, 429.
  • POST/api/v1/auth/loginno API-key scope

    Log in with the passphrase. Sets an httpOnly, SameSite=Strict session cookie authLogin

    Request body
    AuthLogin application/json
    Responses
    200 Signed in (AuthSession) Errors: 400, 401, 403, 409, 429.
  • POST/api/v1/auth/logoutno API-key scope

    End 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 scope

    Sign 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 scope

    First run: set the passphrase and sign in. Only works while no passphrase exists authSetup

    Request body
    AuthSetup application/json
    Responses
    201 Passphrase set; session cookies issued (AuthSession) Errors: 400, 401, 403, 409, 429.
  • GET/api/v1/auth/statusno API-key scope

    Who am I, and is first-run setup needed? Public authStatus

    Responses
    200 Status (AuthStatus)

Debts

  • GET/api/v1/households/{id}/debtsscope: read

    List 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: write

    Create a debt createDebt

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    DebtCreate application/json
    Responses
    201 Created (Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}/debts/{itemId}scope: read

    Get 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: write

    Replace a debt replaceDebt

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    DebtCreate application/json
    Responses
    200 Updated (Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}/debts/{itemId}scope: write

    Merge-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
    object application/json
    Responses
    200 Updated (Debt) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/debts/{itemId}scope: write

    Delete 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: read

    List 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: write

    Add a dependent addDependent

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    DependentCreate application/json
    Responses
    201 Created (Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}/dependents/{dependentId}scope: read

    Get 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: write

    Replace a dependent replaceDependent

    Parameters
    id (path, required, string), dependentId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    DependentCreate application/json
    Responses
    200 Updated (Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}/dependents/{dependentId}scope: write

    Merge-patch a dependent patchDependent

    Parameters
    id (path, required, string), dependentId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (Dependent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/dependents/{dependentId}scope: write

    Remove 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: read

    List 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: write

    Add 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
    PersonCreate application/json
    Responses
    201 Created (Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}/people/{personId}scope: read

    Get 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: write

    Replace a person replacePerson

    Parameters
    id (path, required, string), personId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    PersonCreate application/json
    Responses
    200 Updated (Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}/people/{personId}scope: write

    Merge-patch a person patchPerson

    Parameters
    id (path, required, string), personId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (Person) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/people/{personId}scope: write

    Remove 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: read

    A 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: write

    Replace 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
    PersonCrossBorder application/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: write

    Update 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
    PersonCrossBorder application/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: read

    List 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: write

    Add a expense event addExpenses

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    ExpensesCreate application/json
    Responses
    201 Created (ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/expenses/{itemId}scope: read

    Get 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: write

    Replace a expense event replaceExpensesItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    ExpensesCreate application/json
    Responses
    200 Updated (ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/expenses/{itemId}scope: write

    Partially update a expense event (JSON Merge Patch) patchExpensesItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (ExpenseEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/expenses/{itemId}scope: write

    Remove 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: write

    Reorder the expense events reorderExpenses

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Reordered (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Plan: flows

  • GET/api/v1/plans/{id}/flowsscope: read

    List 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: write

    Add a flow addFlows

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    FlowsCreate application/json
    Responses
    201 Created (Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/flows/{itemId}scope: read

    Get 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: write

    Replace a flow replaceFlowsItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    FlowsCreate application/json
    Responses
    200 Updated (Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/flows/{itemId}scope: write

    Partially update a flow (JSON Merge Patch) patchFlowsItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (Flow) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/flows/{itemId}scope: write

    Remove 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: write

    Reorder the flows (the order is the funding priority) reorderFlows

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Reordered (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Plan: income

  • GET/api/v1/plans/{id}/incomescope: read

    List 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: write

    Add a income event addIncome

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    IncomeCreate application/json
    Responses
    201 Created (IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/income/{itemId}scope: read

    Get 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: write

    Replace a income event replaceIncomeItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    IncomeCreate application/json
    Responses
    200 Updated (IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/income/{itemId}scope: write

    Partially update a income event (JSON Merge Patch) patchIncomeItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (IncomeEvent) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/income/{itemId}scope: write

    Remove 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: write

    Reorder the income events reorderIncome

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Reordered (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Plan: milestones

  • GET/api/v1/plans/{id}/milestonesscope: read

    List 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: write

    Add a milestone addMilestones

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    MilestonesCreate application/json
    Responses
    201 Created (Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/milestones/{itemId}scope: read

    Get 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: write

    Replace a milestone replaceMilestonesItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    MilestonesCreate application/json
    Responses
    200 Updated (Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/milestones/{itemId}scope: write

    Partially update a milestone (JSON Merge Patch) patchMilestonesItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (Milestone) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/milestones/{itemId}scope: write

    Remove 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: write

    Reorder the milestones reorderMilestones

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Reordered (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Plan: planned accounts

  • GET/api/v1/plans/{id}/planned-accountsscope: read

    List 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: write

    Add a planned account addPlannedAccounts

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    PlannedAccountsCreate application/json
    Responses
    201 Created (PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/planned-accounts/{itemId}scope: read

    Get 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: write

    Replace a planned account replacePlannedAccountsItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    PlannedAccountsCreate application/json
    Responses
    200 Updated (PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/planned-accounts/{itemId}scope: write

    Partially update a planned account (JSON Merge Patch) patchPlannedAccountsItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (PlannedAccount) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/planned-accounts/{itemId}scope: write

    Remove 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: write

    Reorder the planned accounts reorderPlannedAccounts

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/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: read

    List 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: write

    Add a planned real asset addPlannedRealAssets

    Parameters
    id (path, required, string), index (query, integer | null)
    Headers
    if-match, idempotency-key
    Request body
    PlannedRealAssetsCreate application/json
    Responses
    201 Created (PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/plans/{id}/planned-real-assets/{itemId}scope: read

    Get 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: write

    Replace a planned real asset replacePlannedRealAssetsItem

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    PlannedRealAssetsCreate application/json
    Responses
    200 Updated (PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/planned-real-assets/{itemId}scope: write

    Partially 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
    object application/json
    Responses
    200 Updated (PlannedRealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/planned-real-assets/{itemId}scope: write

    Remove 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: write

    Reorder the planned real assets reorderPlannedRealAssets

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Reordered (object) Errors: 400, 401, 403, 404, 409, 422, 429, 501.

Plan: settings

  • GET/api/v1/plans/{id}/assumptionsscope: read

    Get 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: write

    Replace the plan's assumptions setAssumptions

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    Assumptions application/json
    Responses
    200 Updated (Assumptions) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/assumptionsscope: write

    Partially update the plan's assumptions (JSON Merge Patch) patchAssumptions

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (Assumptions) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/assumptionsscope: write

    Reset 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: read

    Get 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: write

    Replace the plan's drawdown settings setDrawdown

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    DrawdownSettings application/json
    Responses
    200 Updated (DrawdownSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/drawdownscope: write

    Partially update the plan's drawdown settings (JSON Merge Patch) patchDrawdown

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (DrawdownSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/drawdownscope: write

    Reset 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: read

    Get 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: write

    Replace the plan's flexible spending setFlexSpending

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    FlexSpending application/json
    Responses
    200 Updated (FlexSpending) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/flex-spendingscope: write

    Partially update the plan's flexible spending (JSON Merge Patch) patchFlexSpending

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (FlexSpending) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/flex-spendingscope: write

    Reset 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: read

    Get 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: write

    Replace the plan's leftover policy setLeftover

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    LeftoverPolicy application/json
    Responses
    200 Updated (LeftoverPolicy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/leftoverscope: write

    Partially update the plan's leftover policy (JSON Merge Patch) patchLeftover

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (LeftoverPolicy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/leftoverscope: write

    Reset 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: read

    Get 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: write

    Replace the plan's Monte Carlo settings setMonteCarlo

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    MonteCarloSettings application/json
    Responses
    200 Updated (MonteCarloSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/monte-carlo-settingsscope: write

    Partially update the plan's Monte Carlo settings (JSON Merge Patch) patchMonteCarlo

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (MonteCarloSettings) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/monte-carlo-settingsscope: write

    Reset 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: read

    Get 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: write

    Replace the plan's risk guardrails setRiskGuardrails

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    RiskGuardrails application/json
    Responses
    200 Updated (RiskGuardrails) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/risk-guardrailsscope: write

    Partially update the plan's risk guardrails (JSON Merge Patch) patchRiskGuardrails

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (RiskGuardrails) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/risk-guardrailsscope: write

    Remove 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: read

    Get 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: write

    Replace the plan's tax settings setTax

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    TaxConfig application/json
    Responses
    200 Updated (TaxConfig) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/tax-settingsscope: write

    Partially update the plan's tax settings (JSON Merge Patch) patchTax

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (TaxConfig) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/tax-settingsscope: write

    Reset 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: read

    Get 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: write

    Replace the plan's tax strategy setTaxStrategy

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    TaxStrategy application/json
    Responses
    200 Updated (TaxStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/tax-strategyscope: write

    Partially update the plan's tax strategy (JSON Merge Patch) patchTaxStrategy

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (TaxStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/tax-strategyscope: write

    Remove 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: read

    Get 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: write

    Replace the plan's withdrawal strategy setWithdrawalStrategy

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    WithdrawalStrategy application/json
    Responses
    200 Updated (WithdrawalStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/plans/{id}/withdrawal-strategyscope: write

    Partially update the plan's withdrawal strategy (JSON Merge Patch) patchWithdrawalStrategy

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    object application/json
    Responses
    200 Updated (WithdrawalStrategy) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/plans/{id}/withdrawal-strategyscope: write

    Remove 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: read

    List 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: write

    Create a real asset createRealAsset

    Parameters
    id (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    RealAssetCreate application/json
    Responses
    201 Created (RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • GET/api/v1/households/{id}/real-assets/{itemId}scope: read

    Get 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: write

    Replace a real asset replaceRealAsset

    Parameters
    id (path, required, string), itemId (path, required, string)
    Headers
    if-match, idempotency-key
    Request body
    RealAssetCreate application/json
    Responses
    200 Updated (RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • PATCH/api/v1/households/{id}/real-assets/{itemId}scope: write

    Merge-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
    object application/json
    Responses
    200 Updated (RealAsset) Errors: 400, 401, 403, 404, 409, 422, 429, 501.
  • DELETE/api/v1/households/{id}/real-assets/{itemId}scope: write

    Delete 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 .