Codes Search

Search an index of international codes and standards by jurisdiction, code type, and natural-language query.

Try it without code

The Developer Console at /developer on your Nomic instance includes a Codes Search tool with jurisdiction and code type filters and a live curl preview — useful for exploring available codes and testing queries before integrating the API.

Search codes and standards

POST /codes/search

Returns code sections matching your query, enriched with metadata about the code, jurisdiction, and adoption status.

Scope: developer:agent · Rate limit: Search (60 req / min)

Request body

Field	Type	Required	Description
query	string	Yes	A concise question or description of the code requirement to search for.
jurisdiction	string	Yes	Jurisdiction slug (see Jurisdictions).
codeType	string	Yes	Code discipline name (see Code types).
year	integer	No	Filter to a specific code year.
limit	integer (1–50)	No	Maximum number of results. Default: 10.
keywords	string[]	No	Keywords or phrases to boost in results. Multi-word phrases are treated as exact matches.

Response

{
  "results": [
    {
      "id": "chunk-uuid",
      "citationId": "c-chunk-uuid",
      "pageNumber": 42,
      "content": [
        {
          "citationId": "c-chunk-uuid/1",
          "text": "Section 903.2.1 — Automatic sprinkler systems shall be provided..."
        }
      ],
      "file": {
        "id": "file-uuid",
        "name": "2021 IBC.pdf",
        "mimeType": "application/pdf",
        "versionId": "file-version-uuid",
        "code": {
          "name": "International Building Code",
          "year": 2021
        },
        "jurisdiction": {
          "slug": "texas",
          "name": "Texas"
        },
        "adoption": {
          "effectiveDate": "2023-01-01",
          "amendments": true
        },
        "documentTitle": "2021 International Building Code"
      }
    }
  ]
}

Each result contains:

Field	Type	Description
id	string	Chunk identifier.
citationId	string	Top-level citation ID for the result.
pageNumber	number	Page number in the source document.
content	array	Array of text blocks, each with its own citationId and text.
file	object or null	Source file metadata including code details, jurisdiction, and adoption info.

Errors

Status	Cause
400	Invalid body — missing required fields or invalid enum value.
401	Missing or invalid API key.
403	API key lacks developer:agent scope.
422	Schema validation failed.

Example

curl -X POST "https://<your-domain>.nomic.ai/api/v0/codes/search" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "automatic sprinkler system requirements for high-rise buildings",
    "jurisdiction": "texas",
    "codeType": "Fire Code",
    "limit": 5,
    "keywords": ["sprinkler", "high-rise"]
  }'

---

Jurisdictions

Pass one of the following slugs as the jurisdiction field.

General

general, nfpa

US federal

department-of-defense, department-of-transportation, centers-for-medicare-and-medicaid-services, general-services-administration

US states and territories

alabama, alaska, arizona, arkansas, california, colorado, connecticut, delaware, district-of-columbia, florida, georgia, hawaii, idaho, illinois, indiana, iowa, kansas, kentucky, louisiana, maine, maryland, massachusetts, michigan, minnesota, mississippi, missouri, montana, nebraska, nevada, new_hampshire, new_jersey, new_mexico, new_york, north_carolina, north_dakota, ohio, oklahoma, oregon, pennsylvania, puerto_rico, rhode_island, south_carolina, south_dakota, tennessee, texas, utah, vermont, virginia, washington, west_virginia, wisconsin, wyoming

US cities and counties

austin, baltimore, chicago, clark-nevada, dallas, denver, detroit, dupage-illinois, fort-worth, houston, kansas-city, knoxville, las-vegas, los_angeles, los-angeles-county, nashville, new_york_city, omaha, philadelphia, phoenix, portland, san-antonio, san-diego, san-jose, san_francisco, seattle, sioux-falls, south_holland, wichita-sedgwick

UAE

uae, abu-dhabi

Australia

australia, australian-capital-territory, new-south-wales, northern-territory, queensland, south-australia, tasmania, victoria, western-australia

Singapore

singapore

Brazil

brazil, sao-paulo-state, sao-paulo

Canada

canada, alberta, british_columbia, manitoba, new_brunswick, newfoundland_and_labrador, northwest_territories, nova_scotia, nunavut, ontario, prince_edward_island, quebec, saskatchewan, yukon

---

Code types

Pass one of the following values as the codeType field:

Accessibility Code, Admin Code, Building Code, Civil Code, Design Manual, Electrical Code, Elevator Code, Energy Code, Fire Code, Fuel Gas Code, Green Code, Life Safety Code, Mechanical Code, Medical Facilities Code, OSHA, Performance Code, Plumbing Code, Property Maintenance Code, Residential Code, Structural Code, Swimming Pool Code, Transportation Code, Wildland-Urban Interface Code, Zoning Code