Snapshots

Use snapshots to freeze a calculation. Use share URLs to restore the inputs on a live page. They are not the same thing.

Immutable snapshots

For long Budget / Monte Carlo states (or any frozen audit trail), create an immutable snapshot:

POST /api/v1/share
Content-Type: application/json

{
  "tool_id": "uncertainty-propagate",
  "inputs": { "mode": "quotient", "a": 100, "ua": 0.1, "b": 50, "ub": 0.2 },
  "calculation_version": "1.9.6"
}

Response includes id, frozen result, and links.snapshot → /s/{id}.

GET /api/v1/share/:id
GET /s/:id

• If Cloudflare KV binding SNAPSHOTS is configured, ids are short (cx_…) with ~180-day TTL.
• Otherwise the API returns a self-describing embedded id (cx_e1_…) that needs no server store (URL may be long).
• Simple calculators should keep using query-string share URLs; snapshots are for freeze / audit / oversized state.

Missing snapshots return HTTP 404 with code: "SNAPSHOT_NOT_FOUND". See Errors.

Shareable page URLs

Calculator and converter pages sync inputs into the query string (history.replaceState). Copy the share icon (top-right of the result panel) to copy location.href.

Conventions (electrical):

• Prefer stable data-url / name keys that match API fields where possible (primary, volts, phase, V, I, W, hours, …).
• Active tabs use mode, dir, circuit, and phase query keys.
• Unit-convert electrical tools use the field ids from page config (a, b, pf, …) plus mode.

Example: /calc/electric/amps-to-va?mode=amps-va&primary=12&volts=230&phase=single

Query SSR

Calculator pages under /calc/* rewrite HTML when meaningful query params are present (primary, volts, mode, phase, …). Crawlers and no-JS clients see the computed result, Trust Summary fields, #calculatorx-result JSON, and a result Action merged into the page JSON-LD @graph (#calculatorx-jsonld) that points at the canonical calculator entity — same engines as POST /api/v1/calc. Schema.org describes the tool and this completed calculation; #calculatorx-result remains the calculation contract (inputs, formula, version, verification).

Share URLs restore inputs, not a version lock. Query v is ignored if present (legacy cache-bust / page-revision param). Copy link, Copy JSON, and SSR #calculatorx-result may include calculation_version as attribution of the published engine that rendered the page (for example ?x=144&calculation_version=1.0.3). The live page always runs the current published calculation version shown in Trust Summary / Spec / Evidence. Pin a reproducible calculation version on REST or MCP with CalculatorX-Spec-Version (mismatch → VERSION_MISMATCH). Immutable snapshots live at /s/{id} when frozen.

Examples:

• https://www.calculatorx.com/calc/electric/amps-to-va?primary=12&volts=230&phase=single&mode=amps-va
• Final Grade (Need on final): https://www.calculatorx.com/calc/grade/final-grade?currentInput=85&goalInput=90&weightInput=40&mode=need
• Ratio: https://www.calculatorx.com/calc/math/ratio?aInput=12&bInput=18&mode=simplify
• Subtraction (crawlers see 245 − 147 = 98 in the initial HTML): https://www.calculatorx.com/calc/math/subtraction?minInput=245&subInput=147&mode=difference