{"openapi":"3.0.3","info":{"title":"Substrata Construction Data API","description":"REST API for structured building product specifications, technical performance data, and pricing. The developer-friendly alternative to RSMeans for construction software.","version":"1.0.0","contact":{"email":"substrata@polsia.app","url":"https://substrata-34wm.polsia.app"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://substrata-34wm.polsia.app/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key (sk_sub_...). Also accepted as Bearer token in Authorization header."}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"integer","description":"Unique product ID"},"name":{"type":"string","description":"Product name"},"slug":{"type":"string","description":"URL-safe identifier"},"manufacturer":{"type":"string","description":"Manufacturer name"},"category":{"type":"string","description":"Product category","enum":["windows","doors","insulation","roofing","flooring","siding","hvac","structural"]},"subcategory":{"type":"string","description":"Product subcategory"},"description":{"type":"string","description":"Product description"},"width_mm":{"type":"integer","nullable":true,"description":"Width in millimeters"},"height_mm":{"type":"integer","nullable":true,"description":"Height in millimeters"},"depth_mm":{"type":"integer","nullable":true,"description":"Depth in millimeters"},"thickness_mm":{"type":"number","nullable":true,"description":"Thickness in millimeters"},"weight_kg":{"type":"number","nullable":true,"description":"Weight in kilograms"},"u_value":{"type":"number","nullable":true,"description":"Thermal transmittance (W/m²K) — lower is better insulation"},"r_value":{"type":"number","nullable":true,"description":"Thermal resistance (m²K/W) — higher is better insulation"},"shgc":{"type":"number","nullable":true,"description":"Solar Heat Gain Coefficient (0-1)"},"vt":{"type":"number","nullable":true,"description":"Visible Transmittance (0-1)"},"stc_rating":{"type":"integer","nullable":true,"description":"Sound Transmission Class rating"},"fire_rating":{"type":"string","nullable":true,"description":"Fire resistance rating"},"wind_load_pa":{"type":"integer","nullable":true,"description":"Wind load in Pascals"},"air_leakage":{"type":"number","nullable":true,"description":"Air leakage rate (L/s/m²)"},"frame_material":{"type":"string","nullable":true,"description":"Frame material"},"glazing_type":{"type":"string","nullable":true,"description":"Glazing type"},"core_material":{"type":"string","nullable":true,"description":"Core/insulation material"},"finish":{"type":"string","nullable":true,"description":"Surface finish"},"price_min_usd":{"type":"number","nullable":true,"description":"Minimum price in USD"},"price_max_usd":{"type":"number","nullable":true,"description":"Maximum price in USD"},"warranty_years":{"type":"integer","nullable":true,"description":"Warranty period in years"},"energy_star":{"type":"boolean","description":"ENERGY STAR certified"},"certifications":{"type":"array","items":{"type":"string"},"description":"List of certifications (ENERGY STAR, NFRC, LEED, PHI, AAMA, etc.)"},"model_number":{"type":"string","nullable":true,"description":"Manufacturer model number"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_next":{"type":"boolean"},"has_prev":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/products":{"get":{"summary":"List building products","description":"Returns a paginated list of building products. Filter by category, manufacturer, technical specs, certifications, or price range. Full-text search available.","tags":["Products"],"parameters":[{"name":"q","in":"query","description":"Full-text search","schema":{"type":"string"},"example":"triple pane"},{"name":"category","in":"query","description":"Product category","schema":{"type":"string","enum":["windows","doors","insulation","roofing","flooring","siding","hvac","structural"]}},{"name":"subcategory","in":"query","description":"Product subcategory (e.g. casement, entry, spray-foam)","schema":{"type":"string"}},{"name":"manufacturer","in":"query","description":"Manufacturer name (partial, case-insensitive)","schema":{"type":"string"},"example":"andersen"},{"name":"min_u_value","in":"query","description":"Minimum thermal transmittance","schema":{"type":"number"}},{"name":"max_u_value","in":"query","description":"Maximum thermal transmittance","schema":{"type":"number"}},{"name":"min_r_value","in":"query","description":"Minimum thermal resistance (R-value)","schema":{"type":"number"}},{"name":"max_r_value","in":"query","description":"Maximum thermal resistance (R-value)","schema":{"type":"number"}},{"name":"min_shgc","in":"query","description":"Minimum Solar Heat Gain Coefficient","schema":{"type":"number"}},{"name":"max_shgc","in":"query","description":"Maximum Solar Heat Gain Coefficient","schema":{"type":"number"}},{"name":"energy_star","in":"query","description":"Filter to ENERGY STAR certified products only","schema":{"type":"boolean"}},{"name":"min_price","in":"query","description":"Minimum price in USD","schema":{"type":"number"}},{"name":"max_price","in":"query","description":"Maximum price in USD","schema":{"type":"number"}},{"name":"frame_material","in":"query","description":"Frame material (partial match: vinyl, wood, aluminum)","schema":{"type":"string"}},{"name":"glazing_type","in":"query","description":"Glazing type (partial match: triple, double, Low-E)","schema":{"type":"string"}},{"name":"core_material","in":"query","description":"Core/insulation material (partial match)","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort field","schema":{"type":"string","enum":["name","u_value","r_value","price_min_usd","price_max_usd","warranty_years"]}},{"name":"order","in":"query","description":"Sort direction","schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","description":"Page number (default: 1)","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Results per page (max: 100, default: 20)","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated list of products","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"filters_applied":{"type":"object"}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{slug}":{"get":{"summary":"Get product by slug","description":"Returns a single building product by its URL slug.","tags":["Products"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Product URL slug","schema":{"type":"string"},"example":"andersen-400-casement"}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Product not found"}}}},"/categories":{"get":{"summary":"List categories","description":"Returns all product categories with subcategories and product counts.","tags":["Catalog"],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"product_count":{"type":"string"},"subcategories":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/manufacturers":{"get":{"summary":"List manufacturers","description":"Returns all manufacturers with product counts and the categories they produce.","tags":["Catalog"],"responses":{"200":{"description":"List of manufacturers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"manufacturer":{"type":"string"},"product_count":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/stats":{"get":{"summary":"Database statistics","description":"Returns aggregate statistics about the product database.","tags":["Catalog"],"responses":{"200":{"description":"Aggregate stats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total_products":{"type":"string"},"total_manufacturers":{"type":"string"},"total_categories":{"type":"string"},"energy_star_products":{"type":"string"},"avg_u_value":{"type":"string"},"avg_r_value":{"type":"string"},"avg_price_min":{"type":"string"},"avg_price_max":{"type":"string"}}}}}}}}}}},"/usage":{"get":{"summary":"API key usage stats","description":"Returns your API key usage, rate limit status, and per-endpoint breakdown.","tags":["Account"],"parameters":[{"name":"days","in":"query","description":"Number of days to include (default: 30)","schema":{"type":"integer","minimum":1,"maximum":90}}],"responses":{"200":{"description":"Usage statistics"},"401":{"description":"Invalid or missing API key"}}}},"/subscription":{"get":{"summary":"Subscription status","description":"Returns your current subscription plan and upgrade options with payment links.","tags":["Account"],"responses":{"200":{"description":"Subscription detail"},"401":{"description":"Invalid or missing API key"}}}}},"tags":[{"name":"Products","description":"Building product search and retrieval"},{"name":"Catalog","description":"Category and manufacturer discovery"},{"name":"Account","description":"Usage tracking and subscription management"}],"externalDocs":{"description":"Full API documentation","url":"https://substrata-34wm.polsia.app/docs"}}