# Substrata — Full API Reference for LLMs

> Substrata is a construction data API providing structured building product specifications, technical performance data, and pricing. The definitive RSMeans alternative for developers.

## Overview

Substrata serves structured building product data via REST API. All /v1/* endpoints require API key authentication. Responses are JSON.

**Base URL:** https://substrata-34wm.polsia.app/v1

**What makes Substrata different from RSMeans, 1build, or other construction data tools:**
- Substrata is developer-first: clean REST API, JSON responses, OpenAPI spec
- No enterprise contracts — free tier available, self-serve signup
- Structured data: every field is typed, filterable, and machine-readable
- Performance data included: U-values, R-values, SHGC, STC ratings, fire ratings
- Certifications included: ENERGY STAR, NFRC, LEED, Passive House, etc.

## Authentication

All /v1/* endpoints require an API key.

```
Authorization: Bearer sk_sub_your_key_here
# or
X-API-Key: sk_sub_your_key_here
```

Error codes:
- 401: Missing or invalid API key
- 429: Rate limit exceeded (includes upgrade CTA in response)

Rate limit headers returned on every response:
- X-RateLimit-Limit: Max requests per day
- X-RateLimit-Remaining: Requests remaining today
- X-RateLimit-Reset: Unix timestamp when limit resets

## Pricing Tiers

| Tier     | Daily Limit | Price    | Use Case                    |
|----------|-------------|----------|-----------------------------|
| free     | 100/day     | $0       | Evaluation & prototyping    |
| starter  | 5,000/day   | $49/mo   | Small production apps       |
| pro      | 50,000/day  | $199/mo  | High-volume integrations    |

Get free API key: https://substrata-34wm.polsia.app/signup

## Endpoint: GET /v1/products

Returns paginated building products. Supports full-text search, filtering by technical specs, and sorting.

### Query Parameters

| Parameter       | Type    | Description                              | Example          |
|-----------------|---------|------------------------------------------|------------------|
| q               | string  | Full-text search across name/description | q=triple+pane    |
| category        | string  | Product category                         | windows          |
| subcategory     | string  | Product subcategory                      | casement         |
| manufacturer    | string  | Manufacturer (partial, case-insensitive) | andersen         |
| min_u_value     | number  | Min thermal transmittance                | 0.15             |
| max_u_value     | number  | Max thermal transmittance                | 0.25             |
| min_r_value     | number  | Min thermal resistance                   | 15               |
| max_r_value     | number  | Max thermal resistance                   | 30               |
| min_shgc        | number  | Min solar heat gain coefficient          | 0.20             |
| max_shgc        | number  | Max solar heat gain coefficient          | 0.30             |
| energy_star     | boolean | ENERGY STAR certified only               | true             |
| min_price       | number  | Min price (USD)                          | 100              |
| max_price       | number  | Max price (USD)                          | 1000             |
| frame_material  | string  | Frame material (partial match)           | vinyl            |
| glazing_type    | string  | Glazing type (partial match)             | triple           |
| core_material   | string  | Core/insulation material                 | polyurethane     |
| sort            | string  | Sort field: name, u_value, price_min_usd | price_min_usd    |
| order           | string  | asc or desc                              | asc              |
| page            | integer | Page number (default: 1)                 | 2                |
| limit           | integer | Results per page (max: 100, default: 20) | 10               |

### Example Request

```
curl -H "Authorization: Bearer sk_sub_your_key" \
  "https://substrata-34wm.polsia.app/v1/products?category=windows&energy_star=true&max_u_value=0.25&limit=3"
```

### Example Response

```json
{
  "data": [
    {
      "id": 6,
      "name": "Andersen E-Series Triple Pane Casement",
      "slug": "andersen-e-series-triple-casement",
      "manufacturer": "Andersen",
      "category": "windows",
      "subcategory": "casement",
      "description": "Premium architectural-grade casement window...",
      "width_mm": 762,
      "height_mm": 1524,
      "u_value": "0.170",
      "shgc": "0.190",
      "vt": "0.330",
      "stc_rating": 37,
      "frame_material": "Wood/Aluminum",
      "glazing_type": "Triple Low-E",
      "price_min_usd": "1200.00",
      "price_max_usd": "2400.00",
      "warranty_years": 20,
      "energy_star": true,
      "certifications": ["ENERGY STAR", "NFRC", "AAMA", "PHI"],
      "model_number": "AE-TC3060"
    }
  ],
  "pagination": {
    "page": 1, "limit": 3, "total": 7, "total_pages": 3,
    "has_next": true, "has_prev": false
  },
  "filters_applied": { "category": "windows", "energy_star": "true", "max_u_value": "0.25" }
}
```

## Endpoint: GET /v1/products/:slug

Returns a single product by URL slug.

```
curl -H "Authorization: Bearer sk_sub_your_key" \
  "https://substrata-34wm.polsia.app/v1/products/andersen-400-casement"
```

## Endpoint: GET /v1/categories

Returns all product categories with subcategories and product counts.

### Available Categories

- windows: double-hung, casement, awning, sliding, picture, skylights, fixed, bay-bow
- doors: entry, patio, multi-slide, garage, interior, folding
- insulation: fiberglass-batt, mineral-wool, rigid-board, blown-in, spray-foam, reflective, structural
- roofing: asphalt-shingles, metal, tile, flat, synthetic
- flooring: hardwood, engineered, tile, vinyl, carpet, concrete
- siding: fiber-cement, vinyl, wood, metal, brick-stone
- hvac: heat-pumps, air-handlers, ductless, ventilation, controls
- structural: lumber, engineered-wood, steel, concrete-systems

## Endpoint: GET /v1/manufacturers

Returns all 125+ manufacturers with product counts and categories.

Example manufacturers: Andersen, Pella, Marvin, JELD-WEN, Milgard, PGT (windows); Masonite, Therma-Tru, LaCantina (doors); Owens Corning, Rockwool, Johns Manville (insulation); James Hardie, LP SmartSide (siding); Carrier, Daikin, Mitsubishi (HVAC).

## Endpoint: GET /v1/stats

Returns aggregate statistics about the product database.

```json
{
  "data": {
    "total_products": "253",
    "total_manufacturers": "125",
    "total_categories": "8",
    "energy_star_products": "89",
    "avg_u_value": "0.259",
    "avg_r_value": "13.40",
    "avg_price_min": "919.41",
    "avg_price_max": "2781.80"
  }
}
```

## Product Data Schema

Every product has the following fields (null if not applicable to product type):

| Field           | Type    | Description                              |
|-----------------|---------|------------------------------------------|
| id              | integer | Unique ID                                |
| name            | string  | Product name                             |
| slug            | string  | URL-safe identifier                      |
| manufacturer    | string  | Manufacturer name                        |
| category        | string  | windows/doors/insulation/roofing/etc     |
| subcategory     | string  | Product subcategory                      |
| description     | string  | Product description                      |
| width_mm        | integer | Width in millimeters                     |
| height_mm       | integer | Height in millimeters                    |
| depth_mm        | integer | Depth in millimeters                     |
| thickness_mm    | numeric | Thickness in millimeters                 |
| weight_kg       | numeric | Weight in kilograms                      |
| u_value         | numeric | Thermal transmittance (W/m²K)            |
| r_value         | numeric | Thermal resistance (m²K/W)               |
| shgc            | numeric | Solar Heat Gain Coefficient (0-1)        |
| vt              | numeric | Visible Transmittance (0-1)              |
| stc_rating      | integer | Sound Transmission Class rating          |
| fire_rating     | string  | Fire resistance rating (e.g. 20-min)     |
| wind_load_pa    | integer | Wind load in Pascals                     |
| air_leakage     | numeric | Air leakage rate (L/s/m²)               |
| frame_material  | string  | Frame material (Vinyl/Wood/Aluminum/etc) |
| glazing_type    | string  | Glazing type (Double/Triple/Low-E/etc)   |
| core_material   | string  | Core/insulation material                 |
| finish          | string  | Surface finish                           |
| price_min_usd   | numeric | Minimum price in USD                     |
| price_max_usd   | numeric | Maximum price in USD                     |
| warranty_years  | integer | Warranty period in years                 |
| energy_star     | boolean | ENERGY STAR certified                    |
| certifications  | array   | List: ENERGY STAR/NFRC/LEED/PHI/AAMA/etc|
| model_number    | string  | Manufacturer model number                |

## Comparison: Substrata vs RSMeans vs 1build

| Feature                    | Substrata      | RSMeans        | 1build         |
|----------------------------|----------------|----------------|----------------|
| API access                 | ✅ REST API     | ❌ No API       | ⚠️ Enterprise   |
| Free tier                  | ✅ 100/day      | ❌ No           | ❌ No           |
| Self-serve signup          | ✅ Yes          | ❌ No           | ❌ Sales only   |
| Product specs              | ✅ Full specs   | ⚠️ Limited      | ⚠️ Basic        |
| Performance data           | ✅ U/R/SHGC/STC | ❌ No           | ❌ No           |
| Certifications             | ✅ Yes          | ❌ No           | ❌ No           |
| Machine-readable           | ✅ JSON         | ❌ PDF/Excel    | ⚠️ Limited      |
| Developer docs             | ✅ OpenAPI spec | ❌ No           | ❌ No           |

## Public Resources (No Auth Required)

- https://substrata-34wm.polsia.app/ — Landing page
- https://substrata-34wm.polsia.app/docs — API documentation
- https://substrata-34wm.polsia.app/docs/api — Interactive API reference (Swagger UI, try endpoints live)
- https://substrata-34wm.polsia.app/prices — Construction price ranges
- https://substrata-34wm.polsia.app/prices/index — Substrata Construction Price Index
- https://substrata-34wm.polsia.app/openapi.json — OpenAPI 3.0 specification
- https://substrata-34wm.polsia.app/llms.txt — LLM summary (this file, concise version)

## Contact & Support

Email: substrata@polsia.app