---
title: "One synthetic household, ready to post"
method: GET
path: "/api/v1/project/examples/{id}"
tags: ["project"]
---

# One synthetic household, ready to post

`GET /api/v1/project/examples/{id}`

## Request

- Base URL: `https://worthune.com`
- URL: `https://worthune.com/api/v1/project/examples/{id}`
- Auth: none required

`body` is exactly what POST /api/v1/project accepts.

## Response `200`

The example.

- object
  - `id` string, required
  - `name` string, required
  - `summary` string, required
  - `exercises` string[], required
  - `fictional` unknown, required
  - `body` object, required
    - `household` Household, required: Household object model v0.2.0 (docs/household-schema-spec.md). Validation rejects, never clamps, and returns every issue with a path. Cross-field rules: ids are unique per collection; every ownerId references a member; exactly one primary member and at most one spouse (a spouse requires married_joint); costBasis only on taxable accounts; holdings fractions sum to 1; a socialSecurity block only on social_security streams; endYear never precedes startYear.
      - `schemaVersion` '0.2.0', required
      - `filingStatus` 'single' | 'married_joint', required: MFS and head-of-household are not modeled (the tax module approximates them with Single ceilings and discloses it).
      - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC': Two-letter USPS code (or DC). Optional: without it the household gets federal-only tax treatment, stated in the response assumptions.
      - `members` Member[], required
        - `id` string, required: Unique within members.
        - `birthYear` integer, required
        - `relationship` 'primary' | 'spouse' | 'dependent', required
        - `sex` 'male' | 'female': Needed only for longevity-aware Monte Carlo (NCHS sex-specific life table) and for pension-election / claiming strategies; a run that needs it rejects (never guesses) when an adult member lacks it.
      - `accounts` Account[], required
        - `id` string, required: Unique within accounts.
        - `wrapper` 'taxable' | 'traditional' | 'roth' | 'hsa' | 'plan529' | 'cash' | 'annuity', required
        - `ownerId` string, required: Must reference an existing member id (joint taxable accounts: the primary member).
        - `balance` number, required
        - `holdings` Holdings: Asset-class fractions that must sum to 1 (tolerance 1e-9). Omitted means the account is projected as one blended asset.
          - `us_equity` number
          - `intl_equity` number
          - `bonds` number
          - `cash` number
          - `real_assets` number
          - `other` number
        - `costBasis` number: Taxable accounts only (rejected on any other wrapper): total cost basis for gains treatment.
      - `liabilities` Liability[], required
        - `id` string, required: Unique within liabilities.
        - `kind` 'mortgage' | 'auto' | 'student' | 'credit_card' | 'personal', required
        - `balance` number, required
        - `annualRate` number, required: Annual nominal rate as a fraction (0.065 = 6.5%).
        - `monthlyPayment` number, required
      - `incomes` IncomeStream[], required
        - `id` string, required: Unique within incomes.
        - `ownerId` string, required: Must reference an existing member id.
        - `kind` 'salary' | 'self_employment' | 'rental' | 'pension' | 'social_security', required
        - `annualAmount` number, required
        - `startYear` integer: Calendar year, inclusive. Omitted = already flowing.
        - `endYear` integer: Calendar year, inclusive; must not precede startYear. Omitted = lifelong.
        - `growthRate` number: Annual nominal growth as a fraction. Omitted = the run's defaultIncomeGrowth.
        - `socialSecurity` SocialSecurityBlock: Only on kind = social_security. When present the engine COMPUTES the benefit from the §215(a) formula (the ssa-pia model): annualAmount is ignored and startYear defaults to the year the owner reaches claimAge.
          - `aime` number, required: Average Indexed Monthly Earnings, USD/month.
          - `claimAge` integer, required: Whole-year claiming age.
          - `fullRetirementAge` 66 | 67, required
      - `expenses` ExpenseStream[], required
        - `id` string, required: Unique within expenses.
        - `kind` 'living' | 'goal', required
        - `label` string: The only free-text field in the schema. Stripped before computing on the keyless routes (/project, /book-scan) so no identity reaches the engine or the record hash.
        - `annualAmount` number, required
        - `startYear` integer
        - `endYear` integer: Must not precede startYear.
        - `inflationAdjusted` boolean, required: True: the amount is in today's dollars and rides the inflation assumption.
    - `assumptions` ProjectionAssumptions, required: Unknown keys are rejected — the accepted set is exactly: annualReturn, inflationRate, defaultIncomeGrowth, socialSecurityCola, returnsByWrapper.
      - `annualReturn` number, required: Nominal annual return applied to every account balance (one blended rate).
      - `inflationRate` number, required: Annual inflation applied to inflation-adjusted expense streams.
      - `defaultIncomeGrowth` number, required: Growth for income streams that carry no growthRate of their own.
      - `socialSecurityCola` number: COLA applied to COMPUTED social_security benefits from each benefit's start year. Defaults to inflationRate; pass 0 for a flat benefit.
      - `returnsByWrapper` object: Per-wrapper returns; unlisted wrappers keep the blended annualReturn.
        - `taxable` number: Return for taxable accounts, replacing annualReturn (and any sampled path) for that wrapper.
        - `traditional` number: Return for traditional accounts, replacing annualReturn (and any sampled path) for that wrapper.
        - `roth` number: Return for roth accounts, replacing annualReturn (and any sampled path) for that wrapper.
        - `hsa` number: Return for hsa accounts, replacing annualReturn (and any sampled path) for that wrapper.
        - `plan529` number: Return for plan529 accounts, replacing annualReturn (and any sampled path) for that wrapper.
        - `cash` number: Return for cash accounts, replacing annualReturn (and any sampled path) for that wrapper.
        - `annuity` number: Return for annuity accounts, replacing annualReturn (and any sampled path) for that wrapper.
    - `horizon` ProjectionHorizon, required
      - `startYear` integer, required: First projected calendar year, an integer in [1900, 2150] on every surface.
      - `years` integer, required: Number of years to project.
    - `policy` ProjectionPolicy: Execution choices, hashed into the evidence record — a policy run never hashes like a default run. Unknown keys are rejected.
      - `withdrawalOrder` string[]: A permutation of cash, taxable, traditional, roth — the order deficits are drawn from. Default: cash → taxable → traditional → roth.
      - `rothConversions` object[]: Scheduled Roth conversions: each year's amount moves from traditional accounts (document order) into the first roth account, taxed as ordinary income the same year. A schedule with no roth destination is a 422 from the engine.
        - `year` integer, required
        - `amountUsd` number, required

## Other responses

- `404`: Unknown example.
- `429`: Hourly per-org stateful quota, a per-route durable limit, or the 120 requests/minute per-IP burst backstop.

---

[API](https://skmtc.dev/worthune/apis/worthune-api.md) · [All operations](https://skmtc.dev/worthune/apis/worthune-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worthune/apis/worthune-api/revisions/9f2241072555?raw)