OpenAPI specification

A complete, machine-readable description of every endpoint, generated at build time from the same schemas the server validates requests against — so it cannot describe an API that does not exist.

The document

OpenAPI 1.0.0. Served with CORS open, so a browser can fetch it directly.

https://www.usmortgagecalc.com/openapi.jsonOpen specification

Describes 11 calculation operations plus the reference endpoints, with request and response schemas, examples and error shapes for each.

Generating a client

The point of publishing a spec is that you should not have to hand-write request types.

Client generation

# TypeScript types from the spec
npx openapi-typescript https://www.usmortgagecalc.com/openapi.json -o mortgage-api.d.ts

# A full client, in any supported language
npx @openapitools/openapi-generator-cli generate \
  -i https://www.usmortgagecalc.com/openapi.json \
  -g typescript-fetch \
  -o ./mortgage-client

Reading it programmatically

Useful for agents that discover capabilities at runtime.

Python

import httpx

spec = httpx.get("https://www.usmortgagecalc.com/openapi.json").json()

print(spec["info"]["version"])
for path, methods in spec["paths"].items():
    for method, operation in methods.items():
        print(f"{method.upper():5} {path:44} {operation.get('summary', '')}")

How it stays accurate

Each operation declares its input as a Zod schema. The server validates against that schema at request time, and the build converts the same schema to JSON Schema for the specification. There is no second definition to fall out of sync — a field added to an endpoint appears in the document automatically, and a field removed disappears from it.

The specification is regenerated on every deployment alongside the llms.txt summary and the markdown mirrors of every page, so the machine-readable surfaces and the human-readable ones are always the same age.