Worthune Verified Financial Models

List Worthune's Concordance-tested financial calculation models (an independent second implementation must agree with the engine, per the published spec). Returns model names and spec versions. Call get_model_contract before running a model.

{
  "type": "object",
  "properties": {}
}

Get a model's machine-readable contract: required inputs with types and valid domains, cross-field constraints, sentinel-value meanings, and the government constants (with sources) the model uses. Set include_spec to also receive the full specification markdown (exact formulas, assumptions, exclusions, known issues).

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name from list_models, e.g. 'relocation'"
    },
    "include_spec": {
      "description": "Also return the full spec markdown (default false). Public for the free-sample models; other models need api_key.",
      "type": "boolean"
    },
    "api_key": {
      "description": "Worthune API key (wk_…) — required for include_spec on non-sample models; or send it once as an Authorization: Bearer header.",
      "type": "string"
    }
  },
  "required": [
    "model"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Run a Concordance-tested calculation model. Inputs must satisfy the contract from get_model_contract (all fields required, values inside their domains — out-of-domain requests are rejected, never clamped). The response echoes inputs, spec version, assumptions, triggered sentinels, and sourced constants; outputs are exactly what the engine computed, untouched. Share the matching interactive calculator with users: https://worthune.com/scenarios/<model> for scenario models.

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name from list_models"
    },
    "inputs": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Model inputs per the contract's domains"
    },
    "api_key": {
      "description": "Worthune Pro API key (wk_…). Required for models outside the free sample; the free models run without one.",
      "type": "string"
    }
  },
  "required": [
    "model",
    "inputs"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Verify claims about a model's outputs against the engine before presenting them to a user. Pass the model inputs plus one or more claims ({path, op, value}); each claim comes back verified, violated, or out-of-scope, with the engine's computed value as proof and a decision-record hash tying the verdict to this spec version and these inputs. Out-of-scope means the model does not compute the claimed quantity — this tool never guesses. Use it to check a number you are about to state; use run_model when you want the full output envelope.

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name from list_models"
    },
    "inputs": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Model inputs per the contract's domains"
    },
    "claims": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Output path, e.g. \"monthsToBreakEven\" or \"schedule[3].balance\""
          },
          "op": {
            "description": "Comparison (default ==)",
            "type": "string",
            "enum": [
              "==",
              "<",
              "<=",
              ">",
              ">="
            ]
          },
          "value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              },
              {
                "type": "boolean"
              }
            ],
            "description": "Claimed value; non-finite numbers as \"Infinity\"/\"NaN\" strings"
          }
        },
        "required": [
          "path",
          "value"
        ]
      },
      "description": "Claims to check (max 50)"
    },
    "api_key": {
      "description": "Worthune Pro API key (wk_…). Required for models outside the free sample; the free models verify without one.",
      "type": "string"
    }
  },
  "required": [
    "model",
    "inputs",
    "claims"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a persistent household resource from a household-schema document (docs/household-schema-spec.md: members, accounts by tax wrapper, liabilities, income and expense streams). Validation rejects with JSON-path errors — fix the payload in one pass. Returns the household id to use with get/replace/project_household.

{
  "type": "object",
  "properties": {
    "household": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Household-schema document"
    },
    "label": {
      "description": "Your own name for the household",
      "type": "string"
    },
    "importKey": {
      "description": "Your own stable id for this household: a retry with the same importKey returns the household already created, never a twin (same contract as POST /api/v1/households).",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{1,128}$"
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "household"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a stored household document and its metadata by id.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Household id from create_household"
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the organization's stored households — id, label, advisorRef, version, status, when it was last computed — without the documents (get_household returns one in full). Defaults to active households; GET /api/v1/households returns every status — pass status: "all" for the same listing.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Filter by status (default: active)",
      "type": "string",
      "enum": [
        "active",
        "archived",
        "all"
      ]
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Archive a stored household (never deleted: the row stays readable, leaves the active-household meter, and stops accepting writes or projections). The same operation as DELETE /api/v1/households/{id}.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The append-only history of coordination strategies run on a stored household, newest first — id, strategy, spec version, household version, record hash, when. Metadata only; get_decision returns one in full. Same as GET /api/v1/households/{id}/decisions.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Household id"
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One stored decision in full: the decision object as it was produced, the household version it ran against, and its evidence record with the hashed inputs — enough to re-verify it with /api/v1/records/verify or the SDKs' verifyRecord. Decisions stored before their inputs were retained are returned hash-only and say so. Same as GET /api/v1/decisions/{id}.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "decision_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One household, one picture: the balance sheet by wrapper and owner, income and spending this year, how current the last computation is against the engine's spec (the same drift reasons the weekly scan delivers), the newest decisions, and a data-quality report naming what is missing and what supplying it would unlock. Sums only — no new number of consequence; nothing is stored. Same as GET /api/v1/households/{id}/picture. Pass as_of (YYYY-MM-DD) to pin the date; it is echoed back.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "as_of": {
      "description": "YYYY-MM-DD or ISO timestamp; default now",
      "type": "string"
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Full-document replace with optimistic concurrency: pass expectedVersion (from get_household) and a stale write loses cleanly with the current version instead of clobbering a concurrent change.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "household": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Replacement household-schema document"
    },
    "expectedVersion": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id",
    "household"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Apply a collection-level delta to a stored household without resending the whole document: set scalars (filingStatus, state), upsert entries by id (replace or append), remove entries by id. expectedVersion (from get_household) is REQUIRED — a delta is only meaningful against a version you have read. The merged result is validated in full; a delta can never produce an invalid household.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "expectedVersion": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "set": {
      "description": "Scalar fields: { filingStatus?, state? } (state: null clears it)",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "upsert": {
      "description": "Collection → entries with ids: replace matching ids, append new ones",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        }
      }
    },
    "remove": {
      "description": "Collection → ids to remove",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id",
    "expectedVersion"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Run the deterministic multi-year projection on a stored household — income, RMDs, federal + covered state tax, expenses, amortization, cash flow, net worth per year — optionally with seeded Monte Carlo (same seed, same result). Assumptions: pass your own, pin a profile by id+version, or omit both for the labeled illustrative default; the response always names its assumptionsSource. Every simplification that fired is listed in projection.assumptionsApplied — show your work.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "horizon": {
      "type": "object",
      "properties": {
        "startYear": {
          "type": "integer",
          "minimum": 1900,
          "maximum": 2150
        },
        "years": {
          "type": "integer",
          "minimum": 1,
          "maximum": 80
        }
      },
      "required": [
        "startYear",
        "years"
      ],
      "additionalProperties": false
    },
    "assumptions": {
      "type": "object",
      "properties": {
        "annualReturn": {
          "type": "number"
        },
        "inflationRate": {
          "type": "number"
        },
        "defaultIncomeGrowth": {
          "type": "number"
        },
        "socialSecurityCola": {
          "type": "number"
        },
        "returnsByWrapper": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        }
      },
      "required": [
        "annualReturn",
        "inflationRate",
        "defaultIncomeGrowth"
      ],
      "additionalProperties": false
    },
    "profile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "version"
      ]
    },
    "policy": {
      "description": "Same shape as try_household_projection; applies to the deterministic run and every Monte Carlo path, and is hashed into the record.",
      "type": "object",
      "properties": {
        "withdrawalOrder": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "rothConversions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "year": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "amountUsd": {
                "type": "number"
              }
            },
            "required": [
              "year",
              "amountUsd"
            ]
          }
        }
      },
      "additionalProperties": false
    },
    "monteCarlo": {
      "type": "object",
      "properties": {
        "seed": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "simulations": {
          "type": "integer",
          "minimum": 10,
          "maximum": 5000
        },
        "returnVolatility": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "longevity": {
          "type": "boolean"
        }
      },
      "required": [
        "seed"
      ],
      "additionalProperties": false
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id",
    "horizon"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Twelve FICTIONAL households, each built to exercise a different part of the planning engine — accumulation, a Roth conversion window, drawdown on a low-basis portfolio, spousal Social Security coordination, running out of money, negative amortization, and more. Use one as a starting point for try_household_projection, or as a worked shape when helping someone describe their own household. Pass an id to get the full document back. No API key required.

{
  "type": "object",
  "properties": {
    "id": {
      "description": "An example id; omit to list all twelve with their summaries.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Run the deterministic multi-year household projection on a document you pass in — income, RMDs, Roth conversions, federal and covered-state tax, expenses, amortization, the tax-grossed-up deficit draw, and net worth per year — optionally with a seeded Monte Carlo. NO API KEY, and NOTHING IS STORED: no household is created, no id issued, no record kept. The response carries every simplification that fired in projection.assumptionsApplied and an evidence record whose hash reproduces on an identical document, so you can show your work. Use list_example_households for a starting shape. For a household that persists — with an id, bulk import, webhooks and drift detection — see create_household, which takes a key.

{
  "type": "object",
  "properties": {
    "household": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "A household document: { schemaVersion, filingStatus, state?, members[], accounts[], liabilities[], incomes[], expenses[] }. It has no name field and no account numbers by design. Any expense `label` is stripped before anything is computed."
    },
    "horizon": {
      "type": "object",
      "properties": {
        "startYear": {
          "type": "integer",
          "minimum": 1900,
          "maximum": 2150
        },
        "years": {
          "type": "integer",
          "minimum": 1,
          "maximum": 80
        }
      },
      "required": [
        "startYear",
        "years"
      ],
      "additionalProperties": false
    },
    "assumptions": {
      "type": "object",
      "properties": {
        "annualReturn": {
          "type": "number"
        },
        "inflationRate": {
          "type": "number"
        },
        "defaultIncomeGrowth": {
          "type": "number"
        },
        "socialSecurityCola": {
          "type": "number"
        },
        "returnsByWrapper": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        }
      },
      "required": [
        "annualReturn",
        "inflationRate",
        "defaultIncomeGrowth"
      ],
      "additionalProperties": false,
      "description": "Required here: this surface has no org profile to fall back on."
    },
    "policy": {
      "type": "object",
      "properties": {
        "withdrawalOrder": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "rothConversions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "year": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "amountUsd": {
                "type": "number"
              }
            },
            "required": [
              "year",
              "amountUsd"
            ]
          }
        }
      },
      "additionalProperties": false
    },
    "monteCarlo": {
      "description": "Simulations are clamped to 500 on this keyless surface, and the clamp is reported back.",
      "type": "object",
      "properties": {
        "seed": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "simulations": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "longevity": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "household",
    "horizon",
    "assumptions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Migrate a book (WS3.5): import up to 200 households in one call, with dryRun: true validating everything and writing NOTHING — iterate until the per-row, per-field report is clean, then run for real. Two shapes: households[] of { importKey, label?, household } documents, or template + records — a declarative mapping template (docs/data-migration.md) executed deterministically over raw exported records, so YOU draft the small reviewable template and the engine does the transcription. importKey is the caller's stable id: re-runs are idempotent (already-imported keys skip and report their householdId); imports never overwrite.

{
  "type": "object",
  "properties": {
    "households": {
      "description": "Direct rows: { importKey, label?, household }",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "template": {
      "description": "Mapping template (templateVersion 0.1.0) for the records path",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "records": {
      "description": "Raw exported records, column → string cell",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      }
    },
    "dryRun": {
      "description": "Validate everything, write nothing",
      "type": "boolean"
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WS3.5c: AI drafts the mapping; determinism executes it. Send up to 10 sample records from an export (column → string cell) and get back a DRAFT mapping template for import_households' template + records path. Three deterministic gates run before anything returns: strict JSON, the transcription guard (a numeric const anywhere in the draft is rejected — numbers bind to columns, never to values a model wrote), and the real import dry-run over your sample. Nothing is written. Review the template and the unmappedColumns honesty list, then run import_households yourself with dryRun: true over the full export.

{
  "type": "object",
  "properties": {
    "sampleRecords": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "1-10 sample records, column → string cell"
    },
    "notes": {
      "description": "Context for the draft (what the export is, quirks)",
      "type": "string"
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "sampleRecords"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The Verified Narrative: client- or advisor-ready prose for a stored decision (decision_id) or an inline decision object. A model drafts the narrative FROM the decision; a deterministic gate then extracts every number in the draft and verifies each against the decision's own values — correctly-rounded restatements pass, invented numbers reject the draft whole (one retry, then refusal; a narrative is never patched). The response reports how many claims were checked.

{
  "type": "object",
  "properties": {
    "decision_id": {
      "description": "A stored decision's id (from decide_household)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "decision": {
      "description": "An inline decision object (validated first)",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "audience": {
      "description": "Default \"client\"",
      "type": "string",
      "enum": [
        "client",
        "advisor"
      ]
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Run a Household Coordination Engine strategy on a stored household and get back a ranked decision object with evidence records. Strategies: withdrawal-sequencing (no params); roth-ladder (params.candidates: [{annualAmountUsd, years}]); ss-claiming (params.candidateAges?: {memberId: [ages 62-70]}); asset-location (params.taxRates: {marginalOrdinary, qualifiedAndLtcg} plus params.characteristics or params.illustrativeCharacteristics: true — the illustrative set is labeled not-a-recommendation and is never applied silently); tax-loss-harvesting (params.ordinaryMarginalRatePct, optional longTermRatePct and realizedGains); annual-gifting (params.doneeCount, params.years); pension-election (params.ownerId, startAge, discountRatePct, options — EPVs from the NCHS life table; adults need sex). Alternatives are ranked best-first by a checkable score under a named objective; deltas name their baseline; every projection-backed candidate links its own verifiable record; exclusions are stated in the notes.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "strategy": {
      "type": "string",
      "enum": [
        "withdrawal-sequencing",
        "roth-ladder",
        "ss-claiming",
        "asset-location",
        "tax-loss-harvesting",
        "annual-gifting",
        "pension-election"
      ]
    },
    "horizon": {
      "type": "object",
      "properties": {
        "startYear": {
          "type": "integer",
          "minimum": 1900,
          "maximum": 2150
        },
        "years": {
          "type": "integer",
          "minimum": 1,
          "maximum": 80
        }
      },
      "required": [
        "startYear",
        "years"
      ],
      "additionalProperties": false
    },
    "assumptions": {
      "type": "object",
      "properties": {
        "annualReturn": {
          "type": "number"
        },
        "inflationRate": {
          "type": "number"
        },
        "defaultIncomeGrowth": {
          "type": "number"
        },
        "socialSecurityCola": {
          "type": "number"
        },
        "returnsByWrapper": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        }
      },
      "required": [
        "annualReturn",
        "inflationRate",
        "defaultIncomeGrowth"
      ],
      "additionalProperties": false
    },
    "profile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "version"
      ]
    },
    "params": {
      "description": "Strategy-specific parameters (see the tool description)",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "api_key": {
      "description": "Worthune API key (wk_…)",
      "type": "string"
    }
  },
  "required": [
    "id",
    "strategy",
    "horizon"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}