Codes vertical

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 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.

# 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

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. Common Axis-1 tags: structural, electrical, plumbing, mechanical, energy, fire-protection, egress, accessibility, envelope, interior. Axis-2: residential, commercial, assembly, etc. See topic_tags.md for the full list.

Legal model (short)

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.