Cookbook

These recipes show how an AI agent (Claude, ChatGPT, custom) composes 2-5 BuildCalc API calls into a real user-facing answer. Every recipe cites the actual endpoints + the canonical authority source so the agent can hand the user a verifiable answer.

All examples assume Authorization: Bearer <your-api-key> on every request (omitted here for brevity). Free tier: 1,000 calls/month; see pricing.

Recipe 1 — "Find an HVAC system for my 1,800 sqft house"

Goal: hand the user a short list of cold-climate-suitable heat pumps with their SEER2 + capacity + AHRI cert numbers.

GET /v1/products/categories/hvac?filter[specs.cold_climate.eq]=true&filter[specs.seer2.gte]=18&filter[specs.btu_h_cooling.gte]=30000&filter[specs.btu_h_cooling.lte]=42000&limit=5

Returns ≤5 ENERGY STAR Certified Heat Pumps with cold-climate rating, SEER2 ≥18, and cooling capacity between 30k-42k BTU/h (typical 1,800 sqft single-zone size). Each row carries source_url pointing to the ENERGY STAR row + product_certifications with the AHRI Reference Number for the user to verify on the AHRI Directory.

Agent narrative: "Here are 5 ENERGY STAR cold-climate heat pumps that match your home. The Goodman GSXC180361 (AHRI #1234567) delivers SEER2 16, EER2 12.5, HSPF2 9.5 — that's roughly 18% more efficient than the 2023-spec floor. You can verify the rating at the ENERGY STAR URL."

Recipe 2 — "What R-value do I need for my attic in Climate Zone 5?"

GET /v1/codes/irc/sections?keyword=R-value+attic&edition=2021
GET /v1/products/categories/insulation?filter[specs.r_value.gte]=49&limit=10

First call returns the IRC 2021 §N1102.1.2 section listing R-49 minimum for ceilings in Zone 5. Second call returns 10 ENERGY STAR Certified Insulation products with R-value ≥49. Cite the code section + manufacturer + R-value to the user.

Recipe 3 — "Cost out a high-efficiency toilet replacement for a 2-bath house"

GET /v1/products/categories/plumbing?filter[specs.fixture_type.eq]=toilet&filter[specs.watersense.eq]=true&filter[specs.gpf.lte]=1.28&limit=3
GET /v1/costs/labor?county=06037&trade=plumber&naics=238220

First call: 3 WaterSense-certified toilets ≤1.28 gpf (high-efficiency). Second call: Los Angeles County (FIPS 06037) median plumber wage. Agent estimates: toilet $300-500 + 2-3 hours plumber labor × $48/hr median = total ~$450-650 per fixture installed.

Recipe 4 — "Compare 3 roofing shingles on warranty + wind rating"

GET /v1/products/compare?ids=12,18,42

Returns the 3 product rows side-by-side with common spec keys intersected. Agent ranks them and explains the trade-offs:

CertainTeed Landmark Premium has Class H wind (highest in our catalog), Class A fire, and lifetime warranty. The XT 25 is cheaper at 25-year warranty but only Class F wind. Pick Landmark Premium if you're in a hurricane zone.

Recipe 5 — "Show me NFRC-certified windows from Andersen with U-factor under 0.30"

GET /v1/products/categories/windows?filter[specs.u_factor.lte]=0.30&limit=10

Filter the windows category for cold-climate-qualifying windows (IECC Zone 5+ requires U ≤ 0.30 for vertical fenestration).

Agent narrative: "Here are 10 windows that meet the Zone 5 IECC requirement. Each row's source_url links back to the NFRC CPD listing so a building official can verify on permit submission."

Recipe 6 — "Estimate framing labor + lumber for a 24×40 deck"

GET /v1/products/categories/lumber?filter[specs.grade.eq]=TJI&limit=5
GET /v1/costs/labor?county=06037&trade=carpenter
POST /v1/calc/framing/deck_lumber  {"length_ft": 40, "width_ft": 24, "joist_spacing_in": 16}

The calculator computes board feet needed; products returns suitable engineered I-joists; labor returns the local carpenter median wage. Agent assembles: "240 LF of TJI 230 joists + 80 LF of LVL beam = ~$2,400 materials. 16 hours carpenter @ $42 = $670. Total framing ~$3,070."

Recipe 7 — "Estimate a full kitchen remodel for a 2,000 sqft home in Phoenix"

Goal: pair a federal benchmark with local labor + permit data and calculator outputs so the agent presents a credible all-in budget.

GET /v1/benchmarks/projects/kitchen_remodel?county=04013
GET /v1/costs/labor?county=04013&trade=carpenter
GET /v1/costs/labor?county=04013&trade=plumber
GET /v1/costs/permits?jurisdiction=phoenix_az
POST /v1/calc/concrete/yards {"length_ft":12,"width_ft":15,"depth_in":4}

Maricopa County (FIPS 04013) returns: benchmark median total ~$24k (p50 from Census BPS-derived envelope), local carpenter median $42/hr, plumber median $52/hr, Phoenix permit base $185. The concrete calc covers a slab pour if needed. Agent synthesizes:

A typical kitchen remodel in Phoenix runs $22k–$28k including the $185 building permit, ~60 carpenter hours, ~12 plumber hours, and 1.8 yd³ of slab concrete. Materials are the variable — countertops

• cabinets alone usually consume 40 % of total.

Recipe 8 — "Find ENERGY STAR plumbing fixtures + verify cost feasibility"

GET /v1/products/categories/plumbing?filter[specs.fixture_type.eq]=showerhead&filter[specs.gpm.lte]=1.8&limit=10
GET /v1/costs/materials?category=plumbing&material=showerhead

Plumbing returns ≤10 WaterSense showerheads ≤1.8 gpm; materials returns the PPI-derived current cost index for the showerhead family. Agent ranks by gpm + flags whichever rows are also AHRI-certified.

Recipe 9 — "What heat pump fits my Alaska off-grid cabin?"

GET /v1/products/categories/hvac?filter[specs.cold_climate.eq]=true&filter[specs.hspf2.gte]=10&filter[specs.btu_h_heating.gte]=24000&limit=5
GET /v1/benchmarks/projects/hvac_replacement?state=AK
GET /v1/codes/irc/sections?keyword=heat+pump+cold+climate&edition=2024

HVAC filter yields the cold-climate-certified pumps with HSPF2 ≥10 and ≥24k BTU/h heating. The benchmark gives an Alaska install range. The code call returns the IRC 2024 sections on heat-pump sizing for extreme climates. Agent stitches: spec rationale + code citation + budget envelope into one answer with verifiable provenance.

Recipe 10 — "Pre-flight a Florida hurricane-rated roofing replacement"

GET /v1/products/categories/roofing?filter[specs.wind_class.eq]=H&limit=10
GET /v1/codes/irc/sections?keyword=wind+uplift+shingle&edition=2021
GET /v1/costs/labor?county=12086&trade=roofer
GET /v1/costs/permits?jurisdiction=miami_fl

Roofing returns Class H wind-rated shingles (highest), IRC §R905 cites the wind-uplift attachment requirement, Miami-Dade roofer wage + permit base round out the bid. The source_url on every product row links back to the manufacturer PDF so a roofing inspector can independently verify the Class H rating during permit submission.

Discovery shortcut — what's live today?

GET /v1/products/list
GET /v1/costs/list
GET /v1/benchmarks/list
GET /v1/codes/list

Each returns the current status per category/vertical so agents don't waste user queries asking for a feature that's still coming_soon. The sku_count/total fields hint at how much data is available before drilling in. Current (2026-05-28): 9/10 products categories live (~10,400 SKUs); hardware is gated on LLC formation + USCO DMCA designation.

MCP tools

Every endpoint above is also exposed as an MCP tool at https://api.buildcalcapi.dev/mcp — agents using the Model Context Protocol can call them natively without the HTTP plumbing. See /docs/mcp for the tool list.