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.

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.0",
  "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.

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
    ]
  }
}

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

{
  "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": "dec-sci",
    "value": 12300
  }
}

{
  "coef": 1.23,
  "exp": 4
}

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