{"openapi":"3.1.0","info":{"title":"PermitBird API","version":"1.0.0","description":"Determine whether a project's impacts to waters of the United States qualify for a US Army Corps of Engineers nationwide permit, and look up the compiled 2026 ruleset. Every determination returns the rule provenance behind it and an explicit list of coverage gaps.","contact":{"name":"PermitBird","url":"https://permitbird.com"},"license":{"name":"Proprietary data, free tier available","url":"https://permitbird.com/pricing"}},"servers":[{"url":"https://permitbird.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send \"Authorization: Bearer <key>\". The public sandbox key pb_sandbox_publickey works with no signup."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"docs":{"type":"string"},"fields":{"type":"array","items":{"type":"object"}},"knownValues":{"type":"object","description":"Catalogue of valid values for the fields that failed."}},"required":["code","message"]}}},"DeterminationRequest":{"type":"object","required":["state","district","activity","aquaticResourceType","permanentImpactAcres"],"properties":{"state":{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY","PR","VI","GU"]},"district":{"type":"string","enum":["poa","spa","nab","lrb","sac","lrc","lre","swf","swg","poh","lrh","saj","nwk","swl","spl","lrl","mvm","sam","lrn","nae","mvn","nan","nao","nwo","nap","lrp","nwp","mvr","spk","spn","sas","nws","mvs","mvp","swt","mvk","nww","saw"]},"activity":{"type":"string","enum":["linear-transportation","utility-line-electric","utility-line-pipeline","utility-line-water","bank-stabilization","residential-development","commercial-development","solar-farm","stormwater-facility","boat-ramp","maintenance-repair","aquatic-restoration","agricultural","mining","minor-discharge"]},"aquaticResourceType":{"type":"string","enum":["wetland","stream","open-water","tidal"]},"permanentImpactAcres":{"type":"number","minimum":0},"temporaryImpactAcres":{"type":"number","minimum":0},"streamBedLinearFeet":{"type":"number","minimum":0}}},"Determination":{"type":"object","properties":{"verdict":{"type":"string","enum":["nwp-likely","nwp-with-pcn","individual-permit-likely","insufficient-data"]},"headline":{"type":"string"},"candidates":{"type":"array","items":{"type":"object"}},"pcn":{"type":"object"},"districtLayer":{"type":"object"},"stateLayer":{"type":"object"},"coverageGaps":{"type":"array","items":{"type":"string"}},"provenance":{"type":"array","items":{"type":"object"}}}}}},"paths":{"/api/v1/determine":{"post":{"summary":"Run a permit pathway determination","operationId":"determine","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterminationRequest"}}}},"responses":{"200":{"description":"A determination with provenance and coverage gaps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Determination"}}}},"400":{"description":"The body was not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request. Returns knownValues for the failed fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/determine/batch":{"post":{"summary":"Run up to 100 determinations in one call. Pro tier.","description":"Every project is validated and decided independently and results keep input order, so one invalid row does not discard the batch. Metering charges one unit for the request rather than one per project.","operationId":"determineBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projects"],"properties":{"projects":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/DeterminationRequest"}}}}}}},"responses":{"200":{"description":"One result per input project, in order. Each carries ok:true with a determination, or ok:false with its own field errors."},"400":{"description":"The body was not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is not on the Pro tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The projects array was missing, empty or larger than 100.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/nwp":{"get":{"summary":"List all 57 nationwide permits","operationId":"listPermits","responses":{"200":{"description":"The compiled ruleset."}}}},"/api/v1/nwp/{number}":{"get":{"summary":"Fetch one nationwide permit","operationId":"getPermit","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"integer"},"description":"Numbering is not contiguous. NWPs 26, 47 and 56 are reserved."}],"responses":{"200":{"description":"The permit record."},"404":{"description":"No such permit."}}}},"/api/v1/district":{"get":{"summary":"List all 38 USACE districts","operationId":"listDistricts","responses":{"200":{"description":"Districts with their compilation state."}}}},"/api/v1/district/{code}":{"get":{"summary":"Fetch one USACE district","operationId":"getDistrict","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The district record."},"404":{"description":"No such district."}}}},"/api/v1/state/{code}/401":{"get":{"summary":"Fetch a state Clean Water Act Section 401 certification record","operationId":"getStateCertification","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The certification record, including whether it has been compiled."},"404":{"description":"No such state."}}}},"/api/v1/activity":{"get":{"summary":"List activity identifiers accepted by the determination endpoint","operationId":"listActivities","responses":{"200":{"description":"Activity mappings."}}}}}}