Calculator reference

All 79 calculator endpoints share the same pattern:

POST /v1/calc/{category}/{kind}
Content-Type: application/json
Authorization: Bearer bcapi_...

Discover them programmatically via GET /v1/calc/list (HTTP) or the list_calculators MCP tool. Per-endpoint Pydantic input/output schemas are returned in the response body of any successful call, and the MCP tool catalog includes the full schema for each tool.

Categories overview

Example: concrete yards

POST /v1/calc/concrete/yards

Input:

{
  "length_ft": 10,
  "width_ft": 10,
  "depth_in": 4,
  "waste_factor": 0.10
}

Output:

{
  "cubic_yards": 1.358,
  "cubic_feet": 33.333,
  "bags_60lb": 62,
  "bags_80lb": 49,
  "waste_included_cuyd": 0.123
}

Math: (L × W × D/12) / 27 × (1 + waste) cuyd; bags = ceil(cuyd × 45) for 60lb, ceil(cuyd × 36) for 80lb. Grounded in ACI 332 / IRC R506 with standard premix yields (Quikrete / Sakrete).

Example: electrical panel load (NEC 2026-aware)

POST /v1/calc/electrical/panel-load

{
  "living_area_sqft": 2500,
  "electric_range_va": 12000,
  "electric_dryer_va": 5500,
  "water_heater_va": 4500,
  "hvac_va": 10000,
  "nec_edition": "2026"
}

Returns:

{
  "total_connected_va": 41500,
  "demand_va": 22600,
  "service_amps_at_240v": 94.2,
  "recommended_service_size": "100A",
  "nec_edition_used": "2026",
  "general_lighting_va_per_sqft": 2,
  "code_reference": "NEC Art. 220.82 optional method"
}

NEC 2026 reduced general lighting load from 3 VA/sqft to 2 VA/sqft (LED adoption). Pass nec_edition: "2020" or "2023" for older AHJ-adopted versions — 2023 is the default since most US AHJs are still on 2020/2023.

Complete list

Call GET /v1/calc/list for the live, structured catalog with per-endpoint summaries:

curl https://api.buildcalcapi.dev/v1/calc/list \
  -H "Authorization: Bearer bcapi_..."

Each endpoint has a stable operation_id matching its MCP tool name (e.g., calc_concrete_yards, calc_lumber_stud_count).

Bidirectional codes ↔ calculators

Every calculator response carries a code_reference field naming the section that grounds the formula (e.g. "IRC R311.7.5"). That same identifier is queryable on the codes vertical:

# 1. Run the calc -> get a code_reference
curl -X POST https://api.buildcalcapi.dev/v1/calc/stairs/rise-run \
  -H "Authorization: Bearer bcapi_..." \
  -H "Content-Type: application/json" \
  -d '{"total_rise_in": 96, "tread_depth_in": 11}'
# -> { ..., "code_reference": "IRC R311.7.5", ... }

# Same calc, IRC 2024 jurisdiction — citation follows the renumber
curl -X POST https://api.buildcalcapi.dev/v1/calc/stairs/rise-run \
  -H "Authorization: Bearer bcapi_..." \
  -H "Content-Type: application/json" \
  -d '{"total_rise_in": 96, "tread_depth_in": 11, "irc_edition": "2024"}'
# -> { ..., "code_reference": "IRC R318.7.5", ... }

# 2. Look the section up -> get back to the calc endpoints that implement it
curl https://api.buildcalcapi.dev/v1/codes/irc/sections/R311.7.5 \
  -H "Authorization: Bearer bcapi_..."
# -> { ..., "related_calc_kinds": ["/v1/calc/stairs/rise-run", ...] }

AI agents can pivot in either direction, so a "what does IRC R311.7.5 require?" question flows naturally into "let me run the calculator that implements it" — without fabricated citations.

Validation guarantees

Every coefficient in every calculator was validated against an authoritative US source before commit:

• IRC, IBC, NEC, IECC, IPC, ACI, IBC, TMS, DOE for code-grounded calcs
• GAF, USG, TCNA, Mapei, Sherwin-Williams, Rust-Oleum, ACCA, AHRI, NFRC, Hello Gravel, Simpson Strong-Tie for industry-spec calcs

We treat correctness as part of the product. If you find a value that disagrees with the cited source, file an issue.