Core concepts

The handful of ideas that make Numeratica different — read these once and the rest of the API is obvious.

Authentication & API keys

Every /v1 endpoint requires an API key; health probes (/readyz) and self-serve signup (/v1/signup) are public. Get a free key in seconds — no card. Send the key as a bearer token, or in the X-API-Key header — both are accepted:

# either of these:
-H "Authorization: Bearer nmr_sk_test_xxx"
-H "X-API-Key: nmr_sk_test_xxx"

• Only the SHA-256 hash of a key is stored — the plaintext is shown once at creation and can never be recovered, only rotated.
• A new key works on its first request. Revoking a key (deactivating it) takes effect across all servers within about a minute or two (the auth cache lifetime).
• A missing or invalid key returns 401 unauthorized.

Determinism & result_id

Numeratica calculations are pure functions. Every response carries an engine_version and a result_id, and the same inputs always produce the same answer and the same id — byte for byte.

The result_id is a content hash:

result_id = "<prefix>_" + sha256( canonical_json({ params, engine }) )[:16 hex]
# e.g.  mc_5445a80e48d88d60   (prefix "mc" = Monte Carlo)

• It changes only when an input changes or the engine_version bumps — nothing else.
• Use it to cache responses, dedupe identical requests, diff two runs, and build an audit trail ("this number came from mc_5445a80e48d88d60 on engine montecarlo-1.0.0").

Seeds

Costs and fees

Projections are gross of costs by default. Pass annual_fee_rate (a decimal — 0.01 is 1%) to model the all-in drag of an advisory fee plus fund expense ratios; it is applied as a reduction to the expected return each year, so it compounds inside the return distribution rather than acting as a separate withdrawal.

This matters more than it looks. On our documented example — age 40 to 65 to 95, $500k starting, $30k/yr in, $60k/yr out, 7% return / 12% volatility — a 1% annual fee moves success probability from 89.8% to 75.1% and cuts the median ending balance by about 61%. For an already-retired household the same fee can turn a median ending balance of ~$178k into zero. If you surface these numbers to end users, either pass a realistic rate or tell them the figures are gross of fees.

The same input is accepted by every endpoint that simulates returns — /v1/retirement/monte-carlo, /v1/retirement/withdrawal-strategy, /v1/retirement/accumulation-projection, /v1/retirement/savings-target and /v1/debt-vs-invest. Costs bite hardest in decumulation, where there is no contribution stream to absorb them: a 65-year-old drawing 4.5% from $1.5M goes from 61.9% success at no fee to 47.2% at 1%.

Stochastic engines (such as the retirement Monte Carlo) draw random paths. To make a run exactly reproducible, pass a seed:

• Pass a seed → the same paths every time; the seed is echoed back in the response.
• Omit it → the API generates one and returns it, so the run is still reproducible — capture the seed from the response to replay later.
• The generator is a self-contained splitmix64, independent of the language runtime's PRNG, so output is fixed across versions and platforms.

Error model

Errors share one envelope — a stable machine-readable code plus a human message:

{
  "error": {
    "code": "missing_field",
    "message": "field \"current_age\" is required"
  }
}

Validation is strict and specific: unknown JSON fields are rejected (so typos surface immediately), and missing_field / invalid_params name the exact problem. Input caps keep every call bounded, so deadline_exceeded should never appear in normal use.

Versioning & deprecation

There are two version surfaces:

• API version — the /v1 path prefix. Additive changes (new endpoints, new response fields) ship within /v1 and won't break you. Parse JSON tolerantly (ignore unknown response fields).
• Engine version — each calculation pins its own engine_version (e.g. montecarlo-1.0.0, tax-1.0.0). An engine's numeric output is frozen at a given version; if the math changes, the version bumps — and the result_id for the same inputs changes with it.

That makes engine changes detectable, not silent: watch engine_version (or a changed result_id for known inputs) to know exactly when an engine moved.

Deprecation. We rarely remove anything — additive changes stay in /v1, and a breaking change ships as a new /v2 surface that runs beside /v1 rather than replacing it. If we ever retire a stable (GA) endpoint or field, we give at least 12 months' notice on the wire — RFC 8594 Deprecation and Sunset response headers plus a changelog entry — and the old surface keeps working for the full window. Endpoints explicitly labeled beta carry a shorter window so we can iterate. This is separate from routine kept-current data updates (e.g. a new tax year's tables): those change outputs and are signaled by an engine_version / result_id bump, not a deprecation.

Continuity. Determinism is your safety net — a cached (inputs, seed, engine_version) → result_id stays valid indefinitely, and every kept-current value traces to a public primary source (see Trust), so you can always reproduce a result. Enterprise customers who need a stronger guarantee can ask about source/data escrow, released on defined triggers (e.g. discontinuation without a successor or company wind-down).

Idempotency

Because calculation POSTs are pure and side-effect-free, they are inherently idempotent: sending the same body twice returns the same result and the same result_id, and changes nothing on our side. Retry freely after a network error — no idempotency key required. (Stateful operations like billing, when they arrive, will use explicit idempotency keys.)

Informational, not financial advice

Every response includes a disclaimer. Numeratica returns calculation-engine output — it is not financial, tax, or investment advice, and it does not account for an individual's full circumstances. You are responsible for how results are presented to end users and for any advice layered on top.

"disclaimer": "Calculation engine output for informational purposes only; not financial advice."

Rate limits & quotas

Each API key has a per-minute request budget (a token bucket). Full keys get 200 requests/minute; free keys get 15/minute. Exceed it and the API returns 429 rate_limited with a Retry-After header (in seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{ "error": { "code": "rate_limited", "message": "rate limit exceeded; retry after 1s" } }

• Handle it by backing off for Retry-After seconds, then retrying.
• Free tier — a free key adds a daily quota (250 requests/day, 429 quota_exceeded), caps Monte Carlo at 2,000 simulations per call, and expires 30 days after issue. Need more? Email support@numeratica.com.
• Limits apply per key, per server instance.

Next

• API Reference — every endpoint and schema, from the spec.
• Quickstart — your first call in under five minutes.
• Guides — task-oriented, end-to-end recipes with copy-the-source rendered outputs.