REST API

Public beta HTTP access to the same deterministic engines that power CalculatorX pages. No API key yet — treat responses as informational and verify critical numbers yourself.

Call with a page alias (tool_id, for example amps-to-va). The response always includes the resolved engine. MCP agents should use capability_id instead — see MCP, the agent guide, and the mapping below.

Ids: tool, engine, capability

Use capability_id when you need a stable semantic identity (MCP and the catalog). REST tool_id is a human-friendly page alias. engine is the implementation that ran — do not couple client logic to it.

Not every REST engine is an MCP capability yet. Some grade/dev helpers (for example gpa) stay engine-tested REST until promoted. Browse templated agent capabilities at /capabilities/.

Endpoint

GET  /api/v1/calc
POST /api/v1/calc/:id
Content-Type: application/json

:id may be a public tool alias (amps-to-va) or a callable engine id (amps-va). The response engine is the implementation that ran.

GET /api/v1/calc returns calculation_version, the full list of acceptable ids (canonical + aliases), plus electrical and math catalogs with page links.

Pin a published calculation version with CalculatorX-Spec-Version or calculation_version in the body — mismatch returns HTTP 409. Immutable snapshots and share URLs: Snapshots. Error payloads and rate limits: Errors.

Every supplied pin must agree: header, body calculation_version, legacy calculationVersion, and the corresponding fields inside inputs. Conflicts return HTTP 409 / VERSION_PIN_CONFLICT; there is no body-over-header priority. A supplied pin must be a nonempty string (INVALID_VERSION_PIN, HTTP 400). MCP execute_calculation checks both argument names against each other and an outer CalculatorX-Spec-Version header. Do not silently remove a version lock when retrying.

Request contract 1.0.2 rejects nonzero JSON numeric literals that would convert to binary64 zero, including inside arrays/objects: {"inputs":{"x":1e-400}} returns NUMERIC_UNDERFLOW instead of an exact-zero result. Literal zero (including 0e-400) and representable subnormal values remain distinct; the numerical model may reject a representable input if its outputs are outside its supported range. This transport rule is separate from calculator calculation versions. Decimal strings are accepted only where the calculator declares them, and do not extend binary64 precision. If a client already serialized a rounded value as 0, the server cannot recover its original nonzero source.

POST body

{ "inputs": { … } }

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

Success (200)

{
  "id": "amps-to-va",
  "tool": "amps-to-va",
  "engine": "amps-va",
  "status": "success",
  "inputs": {
    "mode": "amps-va",
    "primary": 12,
    "volts": 230,
    "phase": "single"
  },
  "result": 2760,
  "result_detail": {
    "value": 2760,
    "unit": "VA",
    "formatted": "2,760 VA"
  },
  "formula": {
    "id": "amps-to-va_primary",
    "expression": "S = V_RMS × I_RMS",
    "label": "Single-phase apparent power"
  },
  "assumptions": [
    "AC steady-state with RMS voltage and current magnitudes.",
    "Three-phase mode is balanced sinusoidal AC using line-to-line RMS voltage, where V_LL = √3 V_LN and line currents are equal. IEEE 1459 covers a wider set of conditions; this calculator does not.",
    "Total power factor λ is not applied to VA/kVA results."
  ],
  "warnings": [
    "Result is engine-tested but not expert-reviewed; verify critical use independently."
  ],
  "verification": {
    "engine_tested": true,
    "expert_reviewed": false,
    "source_checked": true,
    "reviewed_by": null,
    "last_reviewed": null
  },
  "api_version": "v1",
  "api_contract_version": "1.0.2",
  "calculation_version": "1.4.3",
  "spec_version": "1.4.3",
  "page": "https://www.calculatorx.com/calc/electric/amps-to-va"
}

result remains the raw engine value for backward compatibility. Prefer result_detail, formula, assumptions, warnings, and verification for agents. Computational verification is defined by CVP. Supplemental domain review is defined by the Review policy.

Reference capability math.scientific_notation (calculation_version 2.0.0) publishes a mode-discriminated input oneOf (convert / engineering / normalize / operate). Share-URL aliases such as numInput and dec-sci are not Agent fields. Its success envelope splits CVP (verification.cvp) from Review policy (review.tier). Other tools still nest review-policy fields under verification until they opt in.

When power_factor (λ) is supplied for electrical.apparent_power, the success body also includes derived.estimated_real_power (P_est = S × λ, unit W). Omit power_factor and derived is omitted. Apparent power itself is unchanged.

Version fields:

Incomplete or illegal inputs return HTTP 400 with status: "error" — never success with a NaN result. A valid empty dataset (for example GPA with no counted credits) is HTTP 200 with engine status: "empty" and a null result value. Full status table, ApiError shape, and rate limits: Errors.

id is the id you requested (page alias or canonical). engine is the resolved engine that ran. Both are always present.

CORS is open (Access-Control-Allow-Origin: *).

Base URL is your CalculatorX host, for example https://www.calculatorx.com.

Runnable examples live on Quick start. Agent tools: MCP. Catalog: /capabilities/.

Engine catalog

Engines are grouped like the site hubs. Field names are case-sensitive and match the JSON inputs object. Electrical page aliases (slug leaf) resolve to the same engines used on the calculator pages.

Finance

Matching pages: Finance calculators.

Electrical (page alias → engine)

Generated from the capability registry. MCP electrical tool ids, including adc-error-budget:

Canonical helper ids (phase-product, scale-quotient, …) remain callable directly. Browse: Electrical · Wire. The full electrical.* MCP list is generated from the capability registry at the bottom of this page.

Math

{
  "inputs": {
    "mode": "of",
    "p": 20,
    "x": 250
  }
}

{ "mode": "of", "value": 50, "Y": 50, "formula": "Y = X × P / 100", … }

{
  "inputs": {
    "v1": 60,
    "v2": 72
  }
}

{ "solve_for": "p", "value": 20, "direction": "increase", … }

{
  "inputs": {
    "y": 3,
    "base": "10"
  }
}

1000

{
  "inputs": {
    "x": 100,
    "base": "10"
  }
}

{
  "solve_for": "y",
  "value": 2,
  "b": 10,
  "x": 100,
  "y": 2
}

{
  "inputs": {
    "x": 10
  }
}

{ "y": ln(10), "value": ln(10), "verification": { "expression": "exp(result)", "passed": true } }

{
  "inputs": {
    "a": 2,
    "n": 10
  }
}

1024

{
  "inputs": {
    "x": 144
  }
}

{
  "principal": 12,
  "real": 12,
  "imag": 0
}

{
  "inputs": {
    "a": 3,
    "b": 4
  }
}

{ "solve_for": "c", "value": 5, "c": 5, "area": 6, "perimeter": 12, … }

{
  "inputs": {
    "a": 27,
    "n": 3
  }
}

3

{
  "inputs": {
    "theta": 30,
    "unit": "deg"
  }
}

0.5

{
  "inputs": {
    "theta": 60,
    "unit": "deg"
  }
}

0.5

{
  "inputs": {
    "theta": 45,
    "unit": "deg"
  }
}

1

{
  "inputs": {
    "x": 0.5
  }
}

{ "deg": 30, "rad": π/6 }

{
  "inputs": {
    "x": 0.5
  }
}

{ "deg": 60, "rad": π/3 }

{
  "inputs": {
    "x": 1
  }
}

{ "deg": 45, "rad": π/4 }

{
  "inputs": {
    "n": 5
  }
}

{
  "n": 5,
  "value": 120,
  "exact": "120",
  "digits": 3,
  "expansion": "5! = 5 × 4 × 3 × 2 × 1",
  "scientific": "1.2 × 10^2",
  "max_n": 5000
}

{
  "inputs": {
    "values": [
      8,
      12,
      20
    ]
  }
}

{ "value": 4, "exact": "4", "formula": "GCF(a,b,c,…) = GCF(GCF(a,b),c,…)", "methods": { "agree": true, … } }

{ "inputs": { "values": [8, 12] } }</code> returns a <code>result</code> object containing <code>{ "value": 24, "exact": "24", "formula": "LCM(a,b,c,…) = LCM(LCM(a,b),c,…)", "methods": { "agree": true, … } }</code>. Share URL: <code>/calc/math/lcm?numsInput=8,12</code>. MCP: <code>execute_calculation</code> with <code>capability_id: "math.lcm"</code> (pin <code>1.0.4</code>). Exact BigInt GCF-identity fold <code>LCM(a,b)=|a/GCF(a,b)×b|</code> (divide first; both nonzero). If any input is 0, LCM = 0; <code>LCM(0,0)=0</code> is a CalculatorX/Python convention (the identity would divide by zero). Integers beyond <code>Number.MAX_SAFE_INTEGER</code> must be decimal strings. Use2–32 integers, each ≤48 digits; matching ordered aliases are required. Result/work data remain complete in summary/full. Explicit empty and unknown/conflicting inputs are rejected; unsafe JSON integers require strings.</p>
<p>REST <code>POST /api/v1/calc/ratio</code> with <code>{ "inputs": { "mode": "simplify", "a": 12, "b": 18 } }

{ "value": "2:3", "terms": [2, 3], "gcf": 6, … }

{
  "inputs": {
    "mode": "operate",
    "op": "+",
    "aNum": 3,
    "aDen": 4,
    "bNum": 1,
    "bDen": 6
  }
}

{ "improper": "11/12", "n": 11, "d": 12, … }

{
  "inputs": {
    "minuend": 245,
    "subtrahend": 147
  }
}

{ "solve_for": "difference", "value": 98, "formula": "a − b = d", … }

{
  "inputs": {
    "sumInput": "1,2,3"
  }
}

{ "value": 6, "sum": 6, … }

{
  "inputs": {
    "a": 8,
    "b": 6
  }
}

{
  "product": 48,
  "productStr": "48",
  "mode": "product"
}

{
  "inputs": {
    "a": 20,
    "b": 4
  }
}

{ "mode": "quotient", "value": 5, … }

{
  "inputs": {
    "x0": 100,
    "ratePct": 5,
    "t": 2
  }
}

110.25

{
  "inputs": {
    "mode": "convert",
    "value": 12300
  }
}

{
  "mode": "convert",
  "coef": 1.23,
  "exp": 4,
  "value": 12300
}

Grade

Courses mode accepts courses as an array of { name?, credits, grade } or compact name:credits:grade rows.

Empty dataset is a valid non-result, not an input error. Zero counted credits return HTTP 200 with { gpa: null, status: "empty" } — never NaN. Negative credits, incomplete prior GPA/credits, or planner A = 0 return engine status: "invalid" with a code (CREDITS_OUT_OF_RANGE, PRIOR_CREDITS_REQUIRED, ADDITIONAL_CREDITS_MUST_BE_POSITIVE, …). Unknown scale ids canonicalize to 4.33; a filled aplus replaces A+ only and keeps other letters on the selected 4.33 or 4.0 base (scale=custom is the legacy 4.33-base alias).

Planner mode adds reachability (secured / attainable / unreachable), unreachable, minAdditionalCredits, and unreachableExact when the target equals the selected scale maximum while current GPA is below it (no finite credit load hits the exact cap; limitApproaches is the scale maximum).

Need-on-final uses Needed = (Goal×100 − Current×(100−W)) / W. W = 0 returns { status: "invalid", code: "WEIGHT_REQUIRED" }. Results include reachability: attainable, unreachable (> 100%), or secured (≤ 0%). Share URL example: /calc/grade/final-grade?currentInput=85&goalInput=90&weightInput=40&mode=need. MCP: search_capabilities → inspect_capability → execute_calculation with capability_id: "education.final_grade" (pin 1.1.1).

Dev / data helpers

Versioning

api_contract_version is 1.0.0. It bumps only when the HTTP response shape or engine contract breaks callers.

Each tool response sets calculation_version / spec_version from that tool's on-page Spec (for example Amps to VA is 1.4.3). Pin integrations against both the numeric result and the tool version. See Versioning & trust.

Limits and beta notes

• No authentication or per-key quota yet — do not hammer the endpoint. Rate limits: Errors.
• Engines throw on illegal inputs → HTTP 400 with an error message.
• Image converters and similar UI-only tools are not in this API.
• Prefer page aliases (amps-to-kw) in integrations so URLs match the site; engine in the response tells you what ran.
• MCP execute_calculation covers the core capability catalog, including education.final_grade, math.factorial, math.fractions, math.gcf, math.lcm, and math.ratio. Registry engines such as gpa and antilog are available on REST POST /api/v1/calc/:id even when they are not yet MCP capabilities.

See also

• Quick start
• MCP
• Errors
• Snapshots
• Versioning & trust
• Capabilities
• Review policy