{"openapi":"3.1.0","info":{"title":"SetbackCalc API","version":"1.0.0","description":"Generator placement clearance reconciliation. Given a generator family and a location, returns the governing clearance for each face of the enclosure — the most restrictive of the manufacturer's listing, the model code and the local ordinance — with the verbatim source quote behind every figure.\n\nCoverage is deliberately narrow and stated honestly: 3 manufacturer families and 4 jurisdictions. Omit `jurisdictionId` for anywhere else and the response carries the manufacturer and model-code layers with an explicit incompleteness warning, rather than a guessed figure.\n\nNo authentication. Rate limited per IP.","contact":{"name":"SetbackCalc","url":"https://setbackcalc.vercel.app"},"license":{"name":"Data is quoted from published manufacturer and code documents; see /methodology"}},"servers":[{"url":"https://setbackcalc.vercel.app"}],"paths":{"/api/calculate":{"post":{"summary":"Reconcile clearances for one site","operationId":"calculatePlacement","tags":["placement"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"familyId":{"type":"string","enum":["generac-air-cooled","cummins-rs","kohler-resa-resc"],"description":"Generator product family. Clearances are published per family, not per kW — see the `ratingsAffectClearances` flag on the result."},"fuel":{"type":"string","enum":["natural-gas","lp-vapour"],"description":"Fuel type the unit is documented for."},"mounting":{"type":"string","enum":["ground","elevated"],"description":"\"ground\" for a ground-level pad (NFPA 37 §4.1.4) or \"elevated\" for a roof, platform or deck (NFPA 37 §4.1.3, which has different figures and a non-combustible surface requirement)."},"jurisdictionId":{"description":"Local jurisdiction, where SetbackCalc holds verified data for it. OMIT this for any jurisdiction not in the list: the result then carries the manufacturer and model-code layers with an explicit incompleteness warning, rather than a guessed local figure.","type":"string","enum":["scarsdale-ny","wall-nj","pemberton-nj","leon-county-fl"]},"districtId":{"description":"Zoning district within the jurisdiction, where that jurisdiction publishes district-dependent setbacks (Scarsdale does).","type":"string","maxLength":40},"conditions":{"description":"Published exceptions the user asserts.","type":"object","properties":{"wallFireRatedOneHour":{"description":"NFPA 37 §4.1.4 exception 1: the adjacent wall of the structure has a fire resistance rating of at least one hour. Unlocks relief from the code fire separation — it does NOT waive the manufacturer's listed distance.","type":"boolean"},"enclosureFireTestDemonstrated":{"description":"NFPA 37 §4.1.4 exception 2: the weatherproof enclosure is non-combustible and a fire within it has been demonstrated not to ignite combustibles outside it. This is the condition Generac's SwRI full-scale fire test satisfies.","type":"boolean"},"localCodeRejectsListing":{"description":"The AHJ declines the third-party listing that a reduced manufacturer figure rests on. Generac's manual expressly contemplates this (\"unless state or local codes dictate otherwise\"), and setting it restores the unreduced NFPA 37 figure.","type":"boolean"},"coAlarmsInstalled":{"description":"FBC Residential §M1905.2.5 exception: the carbon monoxide alarm conditions are met, which reduces the Florida exhaust-to-opening distance from 10 ft to 5 ft (or the manufacturer's figure, whichever is more restrictive).","type":"boolean"}},"additionalProperties":false},"proposed":{"description":"Optional measured or proposed distances in inches, keyed by schedule row id (e.g. \"opening:all:min\"). Supplying these turns the schedule into a pass/fail check.","type":"object","propertyNames":{"type":"string","maxLength":80},"additionalProperties":{"type":"number","minimum":0,"maximum":10000}},"projectRef":{"description":"Reference carried onto the schedule, e.g. \"14 Elm Rise, Lot 3\".","type":"string","maxLength":200}},"required":["familyId","fuel","mounting"],"additionalProperties":false}}}},"responses":{"200":{"description":"The reconciled placement schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"family":{"type":"object"},"jurisdiction":{"type":"object","description":"Either {covered:true, …} or {covered:false, note} — the API never invents a local layer for a jurisdiction it does not hold data for."},"mounting":{"type":"string"},"fuel":{"type":"string"},"schedule":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"opening:all:min"},"aspect":{"type":"string"},"aspectLabel":{"type":"string"},"faceId":{"type":"string"},"faceLabel":{"type":"string"},"bound":{"type":"string","enum":["min","max"]},"requiredInches":{"type":["number","null"]},"governing":{"type":"object","properties":{"layer":{"type":"string","enum":["manufacturer","code","jurisdiction"]},"source":{"type":"string"},"inches":{"type":["number","null"],"description":"null where the source imposes a requirement but publishes no number. Never treated as zero or as satisfied."},"requirement":{"type":"string"},"citation":{"type":"object","description":"Where a figure came from. Every distance the API returns carries one of these, including the verbatim sentence it was transcribed from.","properties":{"label":{"type":"string","example":"Generac Install. Guidelines, Figure 3-2, items B and D"},"document":{"type":"string"},"reference":{"type":"string"},"quote":{"type":"string","description":"Verbatim quote from the source document."},"sourceFile":{"type":"string","description":"Committed extract in the repo this was read from, e.g. docs/…​.txt"}},"required":["label","document","reference","quote","sourceFile"]},"exceptionApplied":{"type":"boolean"},"exceptionSummary":{"type":"string"},"superseded":{"type":"boolean","description":"True when a STRICTLY stricter figure governs this face instead — larger for a minimum, smaller for a maximum. A source stating the same distance as the governing figure is not superseded; see concurring."},"concurring":{"type":"boolean","description":"True when this source states exactly the same distance as the governing figure. The layers agree, so nothing was overridden — useful corroboration for a plans examiner."}}},"considered":{"type":"array","items":{"type":"object","properties":{"layer":{"type":"string","enum":["manufacturer","code","jurisdiction"]},"source":{"type":"string"},"inches":{"type":["number","null"],"description":"null where the source imposes a requirement but publishes no number. Never treated as zero or as satisfied."},"requirement":{"type":"string"},"citation":{"type":"object","description":"Where a figure came from. Every distance the API returns carries one of these, including the verbatim sentence it was transcribed from.","properties":{"label":{"type":"string","example":"Generac Install. Guidelines, Figure 3-2, items B and D"},"document":{"type":"string"},"reference":{"type":"string"},"quote":{"type":"string","description":"Verbatim quote from the source document."},"sourceFile":{"type":"string","description":"Committed extract in the repo this was read from, e.g. docs/…​.txt"}},"required":["label","document","reference","quote","sourceFile"]},"exceptionApplied":{"type":"boolean"},"exceptionSummary":{"type":"string"},"superseded":{"type":"boolean","description":"True when a STRICTLY stricter figure governs this face instead — larger for a minimum, smaller for a maximum. A source stating the same distance as the governing figure is not superseded; see concurring."},"concurring":{"type":"boolean","description":"True when this source states exactly the same distance as the governing figure. The layers agree, so nothing was overridden — useful corroboration for a plans examiner."}}},"description":"Every figure that competed for this row, including the ones that were beaten."},"unresolved":{"type":"string"},"proposedInches":{"type":"number"},"verdict":{"type":"string","enum":["pass","fail","unknown"]}}}},"advisories":{"type":"array","items":{"type":"object"}},"governingDistanceInches":{"type":["number","null"],"description":"Greatest distance required between the enclosure and any feature of the building or site (wall, opening, intake, combustible, service space). Excludes lot-line setbacks, which are measured to the property boundary and reported in greatestLotLineSetbackInches."},"greatestLotLineSetbackInches":{"type":["number","null"],"description":"Greatest setback measured to a property boundary, or null where no covered jurisdiction publishes one. Reported separately because it uses a different datum to the clearances."},"compliance":{"type":"object"}}}}}},"400":{"description":"Body was not valid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}},"required":["error","message"]}}}},"422":{"description":"Input failed validation, or named a family/jurisdiction outside the dataset. The API refuses rather than substituting a default.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}},"required":["error","message"]}}}},"429":{"description":"Rate limited."}}}},"/api/batch":{"post":{"summary":"Reconcile clearances for many sites","operationId":"calculateBatch","tags":["placement"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectName":{"description":"Name for the batch, e.g. a site name.","type":"string","maxLength":200},"sites":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"familyId":{"type":"string","enum":["generac-air-cooled","cummins-rs","kohler-resa-resc"],"description":"Generator product family. Clearances are published per family, not per kW — see the `ratingsAffectClearances` flag on the result."},"fuel":{"type":"string","enum":["natural-gas","lp-vapour"],"description":"Fuel type the unit is documented for."},"mounting":{"type":"string","enum":["ground","elevated"],"description":"\"ground\" for a ground-level pad (NFPA 37 §4.1.4) or \"elevated\" for a roof, platform or deck (NFPA 37 §4.1.3, which has different figures and a non-combustible surface requirement)."},"jurisdictionId":{"description":"Local jurisdiction, where SetbackCalc holds verified data for it. OMIT this for any jurisdiction not in the list: the result then carries the manufacturer and model-code layers with an explicit incompleteness warning, rather than a guessed local figure.","type":"string","enum":["scarsdale-ny","wall-nj","pemberton-nj","leon-county-fl"]},"districtId":{"description":"Zoning district within the jurisdiction, where that jurisdiction publishes district-dependent setbacks (Scarsdale does).","type":"string","maxLength":40},"conditions":{"description":"Published exceptions the user asserts.","type":"object","properties":{"wallFireRatedOneHour":{"description":"NFPA 37 §4.1.4 exception 1: the adjacent wall of the structure has a fire resistance rating of at least one hour. Unlocks relief from the code fire separation — it does NOT waive the manufacturer's listed distance.","type":"boolean"},"enclosureFireTestDemonstrated":{"description":"NFPA 37 §4.1.4 exception 2: the weatherproof enclosure is non-combustible and a fire within it has been demonstrated not to ignite combustibles outside it. This is the condition Generac's SwRI full-scale fire test satisfies.","type":"boolean"},"localCodeRejectsListing":{"description":"The AHJ declines the third-party listing that a reduced manufacturer figure rests on. Generac's manual expressly contemplates this (\"unless state or local codes dictate otherwise\"), and setting it restores the unreduced NFPA 37 figure.","type":"boolean"},"coAlarmsInstalled":{"description":"FBC Residential §M1905.2.5 exception: the carbon monoxide alarm conditions are met, which reduces the Florida exhaust-to-opening distance from 10 ft to 5 ft (or the manufacturer's figure, whichever is more restrictive).","type":"boolean"}},"additionalProperties":false},"proposed":{"description":"Optional measured or proposed distances in inches, keyed by schedule row id (e.g. \"opening:all:min\"). Supplying these turns the schedule into a pass/fail check.","type":"object","propertyNames":{"type":"string","maxLength":80},"additionalProperties":{"type":"number","minimum":0,"maximum":10000}},"projectRef":{"description":"Reference carried onto the schedule, e.g. \"14 Elm Rise, Lot 3\".","type":"string","maxLength":200}},"required":["familyId","fuel","mounting"],"additionalProperties":false},"description":"One entry per property or plot."}},"required":["sites"],"additionalProperties":false}}}},"responses":{"200":{"description":"One schedule per site."},"422":{"description":"Input failed validation."},"429":{"description":"Rate limited."}}}},"/api/schedule.pdf":{"post":{"summary":"Render the placement schedule as a PDF","description":"Returns application/pdf. Free and unauthenticated callers get a watermarked document; the distances are identical in both tiers, because altering a published compliance figure by billing tier would be a liability. The tier used is reported in the X-SetbackCalc-Tier response header.","operationId":"renderSchedulePdf","tags":["placement"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"familyId":{"type":"string","enum":["generac-air-cooled","cummins-rs","kohler-resa-resc"],"description":"Generator product family. Clearances are published per family, not per kW — see the `ratingsAffectClearances` flag on the result."},"fuel":{"type":"string","enum":["natural-gas","lp-vapour"],"description":"Fuel type the unit is documented for."},"mounting":{"type":"string","enum":["ground","elevated"],"description":"\"ground\" for a ground-level pad (NFPA 37 §4.1.4) or \"elevated\" for a roof, platform or deck (NFPA 37 §4.1.3, which has different figures and a non-combustible surface requirement)."},"jurisdictionId":{"description":"Local jurisdiction, where SetbackCalc holds verified data for it. OMIT this for any jurisdiction not in the list: the result then carries the manufacturer and model-code layers with an explicit incompleteness warning, rather than a guessed local figure.","type":"string","enum":["scarsdale-ny","wall-nj","pemberton-nj","leon-county-fl"]},"districtId":{"description":"Zoning district within the jurisdiction, where that jurisdiction publishes district-dependent setbacks (Scarsdale does).","type":"string","maxLength":40},"conditions":{"description":"Published exceptions the user asserts.","type":"object","properties":{"wallFireRatedOneHour":{"description":"NFPA 37 §4.1.4 exception 1: the adjacent wall of the structure has a fire resistance rating of at least one hour. Unlocks relief from the code fire separation — it does NOT waive the manufacturer's listed distance.","type":"boolean"},"enclosureFireTestDemonstrated":{"description":"NFPA 37 §4.1.4 exception 2: the weatherproof enclosure is non-combustible and a fire within it has been demonstrated not to ignite combustibles outside it. This is the condition Generac's SwRI full-scale fire test satisfies.","type":"boolean"},"localCodeRejectsListing":{"description":"The AHJ declines the third-party listing that a reduced manufacturer figure rests on. Generac's manual expressly contemplates this (\"unless state or local codes dictate otherwise\"), and setting it restores the unreduced NFPA 37 figure.","type":"boolean"},"coAlarmsInstalled":{"description":"FBC Residential §M1905.2.5 exception: the carbon monoxide alarm conditions are met, which reduces the Florida exhaust-to-opening distance from 10 ft to 5 ft (or the manufacturer's figure, whichever is more restrictive).","type":"boolean"}},"additionalProperties":false},"proposed":{"description":"Optional measured or proposed distances in inches, keyed by schedule row id (e.g. \"opening:all:min\"). Supplying these turns the schedule into a pass/fail check.","type":"object","propertyNames":{"type":"string","maxLength":80},"additionalProperties":{"type":"number","minimum":0,"maximum":10000}},"projectRef":{"description":"Reference carried onto the schedule, e.g. \"14 Elm Rise, Lot 3\".","type":"string","maxLength":200}},"required":["familyId","fuel","mounting"],"additionalProperties":false}}}},"responses":{"200":{"description":"The PDF schedule.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Input failed validation."}}}},"/api/reference":{"get":{"summary":"The whole published dataset","description":"Every manufacturer rule, model-code baseline and jurisdiction rule with its citation, plus an explicit coverage statement. Use this to check a figure directly against the source rather than calculating.","operationId":"getReference","tags":["reference"],"responses":{"200":{"description":"The dataset."}}}},"/api/projects":{"get":{"summary":"List saved projects","description":"Requires a session. Returns 503 when DATABASE_URL is not configured.","operationId":"listProjects","tags":["projects"],"responses":{"200":{"description":"Projects."},"401":{"description":"No session."}}},"post":{"summary":"Save a project","description":"Requires a session. The schedule is RECOMPUTED server-side from the saved input rather than trusting a client-supplied result.","operationId":"createProject","tags":["projects"],"responses":{"200":{"description":"Saved."},"401":{"description":"No session."}}}},"/api/openapi.json":{"get":{"summary":"This document","operationId":"getOpenApi","tags":["reference"],"responses":{"200":{"description":"The OpenAPI document."}}}}},"tags":[{"name":"placement","description":"Clearance reconciliation."},{"name":"reference","description":"The published dataset and machine-readable docs."},{"name":"projects","description":"Saved projects (account required)."}]}