REST API POC: `POST /api/calculate/mortgage`

Single-endpoint proof-of-concept that validated the dual-product (REST + MCP) architecture pattern for digitalcalculator.info. This page is now a legacy contract reference — the canonical REST grammar is POST /v1/tools/{toolName}/calculate (see the API Reference).

Legacy POC — retired

This single-endpoint POC route (/api/calculate/mortgage) has been retired at the infrastructure level and no longer responds. It demonstrated the contract surface and engineering pattern for the dual-product architecture. The canonical REST grammar is now POST /v1/tools/{toolName}/calculate on https://api.digitalcalculator.info, covering all 13 calculator tools and served by the same engine as the hosted MCP server (https://mcp.digitalcalculator.info/mcp). Build integrations against the canonical grammar — see the API Reference. This page is kept only as a historical contract reference.

Endpoint (historical — retired)

Original method: POST
Original path: /api/calculate/mortgage — retired, now returns 404
Replacement: POST https://api.digitalcalculator.info/v1/tools/mortgage/calculate (canonical grammar, all 13 tools)
Auth: none required for the anonymous tier (Bearer key raises rate limits)
Throttle: global API Gateway throttle — 1.67 rps (≈100 req/min) + burst 50. Per-API, not per-IP

Request

The request body is the bare tool input (no envelope wrapper — the route already encodes the tool name). Same input schema as the MCP mortgage_monthly_payment tool.

Input schema

Input schema for POST /api/calculate/mortgage
Field	Type	Required	Range	Description
`principal`	number (USD)	yes	0 – 100,000,000	Loan principal
`annualRatePercent`	number	yes	0 – 30	Annual rate as whole-number percent (e.g., 6.5)
`termYears`	integer	yes	1 – 50	Loan term in whole years

Sample cURL (canonical grammar)

curl -X POST https://api.digitalcalculator.info/v1/tools/mortgage/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "principal": 300000,
    "annualRatePercent": 6.5,
    "termYears": 30
  }'

Sample request body

{
  "principal": 300000,
  "annualRatePercent": 6.5,
  "termYears": 30
}

Response

Same ToolResult<T> envelope as the MCP surface (per ADR-0039 § 3). Field-for-field identical — tool clients can swap transports without re-parsing.

Sample 200 response

{
  "result": {
    "monthlyPayment": 1896.20,
    "totalInterest": 382633.47,
    "totalPaid": 682633.47
  },
  "disclaimer": "Estimates only. Not financial, tax, or legal advice. Consult a licensed professional before making decisions based on these calculations.",
  "methodology": {
    "url": "https://www.digitalcalculator.info/mortgage-calculator/",
    "version": "2026-05-09"
  },
  "calculatedAt": "2026-05-27T18:42:11.832Z",
  "engineVersion": "1.0.0"
}

Error responses

Errors follow the standard ToolError envelope — single-nested { "error": { code, message, retriable, field? } }. Status mapping:

400 — INPUT_VALIDATION or BUSINESS_RULE
405 — non-POST method (POC guard; gateway should only route POST)
413 — request body > 4 KB (SECR-006 byte-cap)
429 — RATE_LIMIT (API Gateway global throttle)
500 — INTERNAL (logged; report it if you see one)

Sample 400 response

{
  "error": {
    "code": "INPUT_VALIDATION",
    "message": "Number must be greater than or equal to 1",
    "field": "termYears",
    "retriable": false
  }
}

Architecture — dual-product (REST + MCP)

The same monthlyPayment engine powers three surfaces:

Browser calculator at /mortgage-calculator/ (source-of-truth math; engine lifted to TypeScript per ADR-0039 § 5)
MCP server at mortgage_monthly_payment (hosted Streamable HTTP at mcp.digitalcalculator.info/mcp; npm stdio shim: @markcolabs/mcp)
REST POC (this endpoint) for traditional HTTP clients

All three call the same Zod-validated, version-pinned monthlyPayment() function. The engineVersion field in every response confirms math parity. Parity tests at packages/mcp/test/parity/mortgage.test.ts gate the engine against the browser source to the cent.

Why REST AND MCP?

MCP is the right transport for AI agents (Claude Desktop, agentic frameworks, MCP Inspector). REST is the right transport for traditional integrations (server-side jobs, partner systems, browser-side fetch). Same engine, two transports, one source of truth. The REST surface is the “what an enterprise integrator expects to see” companion to the AI-native MCP server.

Path forward

The architecture proved out, and the canonical REST grammar has since been ratified: POST /v1/tools/{toolName}/calculate, served from the dedicated api.digitalcalculator.info subdomain (provisioning). The remaining productization work covers:

General availability of the /v1/tools/{toolName}/calculate route for all 13 calculator tools on api.digitalcalculator.info
Bearer-token auth + per-key rate limits (live today on the MCP surface — see pricing)
Stable versioning policy + deprecation runway
OpenAPI / Swagger surface + SDK generation

Until the REST companion is generally available, use the MCP endpoint and treat this POC page as contract reference only. The POC route may be removed or moved without notice.

References

MCP API Reference — full input/output schemas for all 13 calculator tools
Mortgage Calculator — the browser surface (same engine)
REST-API-POC-2026-05-27 — full architectural rationale + path-forward gate (internal design doc)
ADR-0039 — MCP Tool Contract (envelope shape reused here; internal design doc)
ADR-0041 — v1 Contract Reconciliation (single-nested error shape per D6; internal design doc)

REST API POC: POST /api/calculate/mortgage