BuildCalc API

Codes vertical

IRC/IBC/NEC/IECC/IPC section metadata, calculator cross-references, and per-jurisdiction adoption matrix.

What's in it

BuildCalc API ships a first-party codes reference vertical so AI agents and developers can ground citations against a stable source instead of fabricating section numbers.

  • 937 hand-curated sections across IRC (2021 + 2024), IBC 2024, NEC (2023 + 2026), IECC 2024, IPC 2024.
  • Per-section calculator cross-references — every section returns the list of /v1/calc/* endpoints that implement its formulas.
  • Per-jurisdiction adoption matrix — which edition of each code is currently adopted by each US state.

Per ADR-0014 (scope rationale available on request via [email protected]) the vertical stores only metadata (section number, title, chapter, parent, topic tags, publisher viewer deep link). No verbatim or paraphrased code text is republished.

Endpoints

All paths are prefixed https://api.buildcalcapi.dev. Authentication and rate-limit policy are the same as the calculator endpoints (Bearer bcapi_…).

GET /v1/codes/list

Discovery — lists the 5 code families with their default edition and available editions.

curl https://api.buildcalcapi.dev/v1/codes/list \
  -H "Authorization: Bearer bcapi_..."
{
  "codes": [
    {"id":"irc","name":"International Residential Code","publisher":"ICC",
     "default_edition":"2021","available_editions":["2021","2024"],
     "description":"Residential 1- and 2-family dwellings, townhouses ≤3 stories."},
    {"id":"ibc","name":"International Building Code","publisher":"ICC",
     "default_edition":"2024","available_editions":["2024"], "...":"..."},
    {"id":"nec","name":"National Electrical Code","publisher":"NFPA",
     "default_edition":"2023","available_editions":["2023"], "...":"..."}
  ],
  "total": 5
}

GET /v1/codes/{code_id}

Code metadata + adoption rollup (how many US jurisdictions are currently on each edition).

curl https://api.buildcalcapi.dev/v1/codes/irc \
  -H "Authorization: Bearer bcapi_..."
{
  "id": "irc",
  "default_edition": "2021",
  "available_editions": ["2021", "2024"],
  "adoption_stats": {
    "total_jurisdictions_tracked": 48,
    "by_edition": {"2024": 7, "2021": 24, "2018": 12, "2015": 5}
  }
}

GET /v1/codes/{code_id}/sections

List sections with optional filters.

ParamTypeDescription
editionstring?Edition filter (default = code's default_edition)
chapterstring?Filter by chapter (e.g. "3", "7")
topicstring?Filter by tag (e.g. "stairs", "gfci")
qstring?Full-text search on section_number + section_title + topic_tags
limitint1-200, default 50
offsetint≥0, default 0
# IRC chapter 3 sections
curl 'https://api.buildcalcapi.dev/v1/codes/irc/sections?chapter=3&limit=5' \
  -H "Authorization: Bearer bcapi_..."

# Search for "concrete" across IRC default edition
curl 'https://api.buildcalcapi.dev/v1/codes/irc/sections?q=concrete' \
  -H "Authorization: Bearer bcapi_..."

# IRC 2024 (dual-edition — chapter 3 was renumbered)
curl 'https://api.buildcalcapi.dev/v1/codes/irc/sections?edition=2024&chapter=3' \
  -H "Authorization: Bearer bcapi_..."

Response shape:

{
  "sections": [
    {
      "code_id": "irc",
      "edition": "2021",
      "section_number": "R311.7.5",
      "section_title": "Stair Treads and Risers",
      "chapter": "3",
      "parent_section_number": "R311.7",
      "topic_tags": ["egress", "residential", "stairs"],
      "viewer_deep_link": "https://codes.iccsafe.org/content/IRC2021P2/...#R311.7.5",
      "source_url": "https://up.codes/s/stair-treads-and-risers"
    }
  ],
  "total": 199,
  "code_id": "irc",
  "edition": "2021"
}

total is the row count matching all filters — not the page size — so clients can paginate confidently.

GET /v1/codes/{code_id}/sections/{section_number}

Section detail. Same shape as a row above, plus related_calc_kinds:

curl https://api.buildcalcapi.dev/v1/codes/irc/sections/R311.7.5 \
  -H "Authorization: Bearer bcapi_..."
{
  "section_number": "R311.7.5",
  "section_title": "Stair Treads and Risers",
  "edition": "2021",
  "related_calc_kinds": [
    "/v1/calc/stairs/rise-run",
    "/v1/calc/stairs/stringer-count"
  ],
  "...": "..."
}

related_calc_kinds is the bridge between codes and calculators. Every calculator response returns a code_reference (e.g. "IRC R311.7.5") which maps back to a section here, and that section's related_calc_kinds points back to the calc endpoints. AI agents can pivot in either direction.

GET /v1/codes/jurisdictions/{jurisdiction}/applicable

Adoption matrix for a US state.

curl https://api.buildcalcapi.dev/v1/codes/jurisdictions/CA/applicable \
  -H "Authorization: Bearer bcapi_..."
{
  "jurisdiction_code": "CA",
  "jurisdiction_name": "California",
  "applicable": [
    {"code_id":"nec","edition":"2023","has_amendments":true,
     "amendment_notes":"Modified as the CA Codes and are mandatory minimum statewide",
     "source_url":"https://codecheck.com/code-adoption-by-state/"},
    {"code_id":"irc","edition":"2024","has_amendments":true, "...":"..."},
    {"code_id":"ibc","edition":"2021","has_amendments":false,
     "amendment_notes":"Source: ICC Master I-Code Adoption Chart (Jan 2024 snapshot)..."}
  ]
}

Path param is the 2-letter US state code (CA, TX, NY, …). Returns 404 if no adoption rows are tracked for that jurisdiction.

Editions and IRC dual-edition

IRC ships two editions under the same code id:

  • 2021 is the default (most adopted in the US — ~40-50% of jurisdictions).
  • 2024 is the latest; chapter 3 was substantially renumbered (stairways moved from R311.7 to R318.7, CO alarms moved from R315 to R311).

Calculator citations are edition-aware: IRC-citing calcs (currently the stairs calcs) accept an optional irc_edition: "2021" | "2024" input field and return the code_reference string in the requested edition's numbering. Default is "2021" since most US jurisdictions are still on IRC 2021. The related_calc_kinds lookup table on the codes vertical has entries for both numbering schemes too, so a query for /v1/codes/irc/sections/R318.7.5?edition=2024 returns the same stair-related calculators as /v1/codes/irc/sections/R311.7.5.

NEC also ships two editions under the same code id:

  • 2023 is the default (most adopted in 2026 — 23 of 49 tracked US states).
  • 2026 is the latest (NFPA 70-2026, published Oct 2025; the calculator at /v1/calc/electrical/panel-load applies the new 2 VA/sqft general lighting load when nec_edition="2026").

NEC 2026 is the largest structural overhaul since 1975 — Article 220 was renumbered to Article 120 (load calculations moved from Chapter 2 to Chapter 1). So 220.12 / 220.42 / 220.82 in NEC 2023 are 120.12 / 120.42 / 120.82 in NEC 2026. calc_links.py carries entries for both numbering schemes so the bidirectional calc↔codes loop works regardless of which edition the user pins to. Section numbers that didn't move (210.x, 250.x, 310.x, 314.16, 358.22) resolve identically.

Other codes ship single-edition: IBC/IECC/IPC = 2024.

Adoption matrix sources

SourceCodes coveredRefresh
codecheck.com/code-adoption-by-stateNEC, IRCquarterly (2026-02 last)
ICC Master I-Code Adoption Chart (Jan 2024 PDF)IBC, IECC, IPCannual snapshot

Rows from the ICC PDF carry an explicit staleness note in amendment_notes ("Re-verify against jurisdiction publications for time-sensitive use").

Topic tag taxonomy

topic_tags values are drawn from a fixed vocabulary. The schema enforces lowercase kebab-case. Two-axis classification:

AxisTags
Domainstructural, electrical, plumbing, mechanical, energy, fire-protection, egress, accessibility, envelope, interior, foundation, roofing, lighting, ventilation, seismic
Occupancyresidential, commercial, assembly, mixed-use, industrial
Elementstairs, gfci, afci, headroom, r-value, u-factor, shgc, load-bearing, header, panel, dfu, wsfu

A section can carry multiple tags across all three axes — e.g. R311.7.5 ("Stair Treads and Risers") is tagged ["egress", "residential", "stairs"]. Query ?topic=stairs returns every section sharing that element tag across editions and codes.

Per ADR-0014:

  • Section numbers and titles are short factual labels — Feist applies, no copyright concern.
  • Section body text is NEVER republished — neither verbatim nor paraphrased. The viewer_deep_link field sends callers to the publisher's free-access portal (ICC Digital Codes, NFPA Link) for the full text.
  • State amendments are flagged via has_amendments boolean and an amendment_notes free-form summary — but never reproduced.

Changelog

Notable changes shipped to BuildCalc API. Mirrors CHANGELOG.md in the repo.

Cookbook

End-to-end agent recipes composing 2-5 BuildCalc API calls into real user-facing answers — HVAC sizing, insulation, plumbing fixtures, kitchen remodel budget, hurricane-rated roofing, off-grid heat pumps

On this page

What's in itEndpointsGET /v1/codes/listGET /v1/codes/{code_id}GET /v1/codes/{code_id}/sectionsGET /v1/codes/{code_id}/sections/{section_number}GET /v1/codes/jurisdictions/{jurisdiction}/applicableEditions and IRC dual-editionAdoption matrix sourcesTopic tag taxonomyLegal model (short)