Changelog

What's changed in the API — new endpoints, platform changes, and engine versions. Changes are additive within /v1; numeric output only moves on an engine_version bump (see versioning).

2026-07 · v1.3.0 — 16 new calculators (mortgages, benefits, everyday money) + domain-grouped reference

• Mortgages — five decisions, one call each: /v1/mortgage/rent-vs-buy, /v1/mortgage/affordability (DTI-bound price + payment split), /v1/mortgage/points (buydown breakeven), /v1/mortgage/term-comparison (15-vs-30 with invest-the-difference), and /v1/mortgage/refinance (breakeven + lifetime saving).
• Everyday money — /v1/savings-waterfall (match → HSA → IRA → 401(k) → taxable, MAGI-checked), /v1/roth-vs-traditional (with the taxable-side drag and the breakeven retirement rate), and /v1/debt-payoff (avalanche vs snowball, full payoff schedule).
• Workplace benefits — /v1/benefits/health-plan (HDHP+HSA vs PPO in after-tax dollars) and /v1/benefits/dependent-care (FSA exclusion vs the §21 credit).
• Tax — /v1/tax/w4-checkup (projected refund/balance-due + per-paycheck fix, safe-harbor-aware) and /v1/tax/filing-status (MFJ vs MFS comparison).
• Education — /v1/education/student-loan-refi (private-refi breakeven vs federal protections) and /v1/education/529-to-roth (SECURE 2.0 rollover planner).
• Retirement / Medicare — /v1/retirement/self-employed (solo-401(k)/SEP sizing from SE income) and /v1/medicare/late-enrollment-penalty (Part B/D lifetime penalty cost).
• Reference & guides reorganized by domain — every operation carries a domain tag, the reference sidebar groups by it, and the guides index now has five domain sections including three new guides (buying a home, the savings waterfall, open enrollment).

2026-07 · Composition — POST /v1/batch

• Batch — run up to 20 calculators in one call (one result per sub-request, order preserved). Each sub-request is metered and validated exactly like a direct REST call; a sub-failure is isolated (the batch always returns 200); rate limiting is all-or-nothing; and identical batches return an identical result_id. Removes the app-side orchestration for a "current vs proposed" plan view. Tagged Platform in the reference.

2026-07 · v1.2.0 — 12 new calculators (insurance, investing, education, tax)

• Insurance & risk-management — three new endpoints: /v1/insurance/life-needs (capital-needs/DIME + human-life-value), /v1/insurance/disability-needs (after-tax income-replacement gap), and /v1/insurance/long-term-care (care-cost projection + self-insure-vs-insure).
• Investment mechanics — /v1/portfolio/rebalance (drift, trades, tax-aware contributions-first) and /v1/portfolio/glidepath (age-based equity/bond path).
• Education — /v1/education/student-loan (standard vs the new RAP vs IBR, with PSLF; reflects the 2025 OBBBA changes) and /v1/education/aid-estimate (FAFSA Student Aid Index, 2026-27 tables).
• Tax & retirement — /v1/tax/estimated-tax (§6654 safe harbors + underpayment-penalty estimate), /v1/tax/survivor-transition (the widow(er)'s-penalty MFJ→single jump), and /v1/retirement/sepp (72(t) early-withdrawal schedule).
• Each is versioned, in the API reference, and available as an MCP tool. Every year-keyed data table ships with a checksummed primary-source snapshot.

2026-07 · v1.1.0 — 10 new calculators

• 10 new endpoints — effective-marginal-rate map, couples Social Security claiming optimizer, QCD planner, ACA premium-tax-credit optimizer, concentrated-position liquidation schedule, QSBS (§1202) exclusion, NUA vs rollover, S-corp salary optimizer, backdoor / mega-backdoor Roth, and QLAC. Each is versioned, in the API reference, and available as an MCP tool.
• /v1/tax/estimate now accepts charitable_contributions (the §170 0.5%-of-AGI floor for 2026+).
• Error responses — 401 / 429 / 503 are now documented on every endpoint, so generated clients model them. A key-store outage returns a retryable 503, never a misleading 401.
• Monte Carlo accuracy — fixed a PRNG defect that correlated parallel simulation paths, understating the sampling error on quoted success probabilities. Same inputs + seed still return the same result.

2026-06 · Self-serve free keys, MCP bridge, and hardening

• Free, self-serve API keys — POST /v1/signup (public, gated by a Cloudflare Turnstile challenge) mints a free key that expires in 30 days. Get a free key — no card, no waiting.
• Free tier — free keys are rate- and quota-limited (15 req/min, 250 req/day) with Monte Carlo capped at 2,000 simulations per call; full keys are unaffected.
• Open-source MCP bridge — @numeratica/mcp, a zero-dependency npx package, connects any stdio MCP client to the hosted /mcp endpoint. See the MCP guide.
• Browser "try it" — scoped CORS lets the API Reference's request client call the live API from your browser (an origin allowlist, never *).
• Security hardening — Cloud SQL TLS, deletion protection + point-in-time recovery, least-privilege service accounts, nosniff, and a central client-error sanitizer. No API change.

2026-06 · Live, with persistence, limits, and tracing

• New endpoint — POST /v1/tax/social-security-benefits: §86 Social Security benefit taxation, including the "tax torpedo" effective-rate effect.
• Rate limiting — each API key now has a per-minute budget; over-budget requests return 429 with a Retry-After header. See rate limits.
• Persistence & key management — keys and usage are Postgres-backed; keys can be minted and revoked, and a new key works on its first request.
• Request tracing — operational tracing to Cloud Trace (no API change).
• Hosted — the API is live at api.numeratica.com over HTTPS.

2026-06 · Equity compensation & tax-alpha

• Equity comp — ISO and RSU, NSO exercise, ESPP disposition, the §83(b) election comparison, ISO AMT-capacity (crossover), and an ISO exercise schedule.
• Tax-aware planning — gain-harvesting, tax-loss-harvesting benefit, and asset-location endpoints.

2026-06 · MCP & the engine baseline

• MCP — a hosted Model Context Protocol endpoint (Streamable-HTTP) at /mcp, with tools generated from the API request schemas, so AI agents can call the calculators directly (same key auth).
• Engine baseline — all engines pinned to a clean 1.0.0 baseline.
• Tax-engine fidelity — credits, AMT, §199A QBI, and deduction phase-outs.

2026-06 and earlier · v1 calculators

• The core suite — retirement Monte Carlo, time-value-of-money, RMD, Social Security, Roth conversion, IRMAA, tax-aware withdrawal sequencing and strategy, debt-vs-invest, state income tax, healthcare costs, annuity, longevity, and more (60 endpoints at the time).
• Determinism from day one — every result carries an engine_version and a deterministic result_id; the OpenAPI spec is the contract.

Engine versions

Every engine pins its own engine_version — all are 1.0.0 today. During the pre-launch eval phase, an output-affecting correction may ship pinned at 1.0.0 (e.g. the v1.1.0 Monte Carlo PRNG fix); from general availability onward, any change to an engine's math bumps its version so the result_id for the same inputs changes with it — engine changes detectable, never silent.

Stay informed

Questions, integration help, or want to be notified of changes? Email support@numeratica.com. A subscribe option and a formal deprecation-notice policy are on the way.