Calculation API

Public beta HTTP access to the same deterministic engines that power many CalculatorX pages. Built for agents, scripts, and lightweight integrations. No API key yet — treat responses as informational and verify critical numbers yourself.

Endpoint

POST /api/v1/calc/:engineId
Content-Type: application/json

Body

{ "inputs": { … } }

You may also send the inputs object as the top-level JSON body (without wrapping in inputs).

Success (200)

{
  "id": "loan-payment",
  "result": { "payment": 1580.17, "totalPaid": 568861.22, "totalInterest": 318861.22 },
  "calculation_version": "1.0.0"
}
Status Meaning
200 Calculation succeeded
400 Invalid JSON or inputs the engine rejects
404 Unknown engineId
405 Method other than POST (OPTIONS allowed for CORS)

CORS is open (Access-Control-Allow-Origin: *). Only POST and OPTIONS are supported.

Base URL is your CalculatorX host, for example https://calculatorxcloudflare.pages.dev.

Quick start

curl -X POST 'https://calculatorxcloudflare.pages.dev/api/v1/calc/loan-payment' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"principal":250000,"ratePct":6.5,"termMonths":360}}'

curl -X POST 'https://calculatorxcloudflare.pages.dev/api/v1/calc/compound-interest' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"principal":1000,"ratePct":5,"years":10,"compoundsPerYear":12}}'

Engine catalog

Engines are grouped like the site hubs. Field names are case-sensitive and match the JSON inputs object.

Finance

engineId Inputs Result highlights
compound-interest principal, ratePct, years, compoundsPerYear fv, interest
simple-interest principal, ratePct, term, termUnit (years / months / days), optional mode interest, balance
vat mode (add / extract), amount, ratePct net, vat, gross
loan-payment principal, ratePct, termMonths payment, totalPaid, totalInterest
amortization same as loan-payment payment totals + schedule (first 12 periods)
roi cost, gain roiPct, profit
break-even fixedCost, price, variableCost units, contribution, revenue
profit-margin revenue, cost marginPct, profit
cagr startValue, endValue, years cagrPct
discount originalPrice, discountPct salePrice, saved
markup cost, sellingPrice markupPct, marginPct
present-value futureValue, ratePct, years, compoundsPerYear pv
savings-goal goal, ratePct, years, principal payment

Matching pages: Finance calculators.

Electrical

engineId Inputs (summary) Notes
amps-va mode (amps-va / va-amps / amps-kva), primary, volts, phase (single / three) Apparent power / current
watts-amps dir (w-a / a-w), powerOrCurrent, volts, circuit, pf Real power ↔ current
ohms-law any two of V, I, R, P Returns the full set
power-factor mode, V, I, P_kW S, pf, Q
voltage-drop mode, I, length_m, R_ohm_per_km Drop in volts
voltage-divider divider inputs as used by the page engine Two-resistor divider
energy W, hours kWh
energy-cost energy × rate fields Cost estimate
watt-volt-amp W / V / A relationships
electricity-bill consumption + rate fields Bill estimate
awg / swg gauge + optional field (mm / mm2) Wire geometry
phase-product, phase-quotient, product, quotient, scale-product, scale-quotient, scale, sqrt-product, inverse-square-product Shared electrical helpers Used by multiple electric pages

Browse: Electrical calculators.

Dev / data helpers

engineId Inputs Result
base64 mode (encode / decode), text Encoded or decoded string
url-codec mode (encode / decode), text URL-encoded string
ascii char dec, hex, bin
http-status code Status metadata
hex-to-rgb hex r, g, b
rgb-to-hex r, g, b #RRGGBB
base-convert value, fromBase, toBase Converted string

Versioning

Responses include calculation_version (currently 1.0.0). When formulas change in a breaking way, this field will bump. Prefer pinning expectations in your tests against both the numeric result and the version string.

On-page specs and the repo’s npm run test:calc-specs suite stay the source of truth for formula drift.

Limits and beta notes

See also