{"openapi":"3.0.3","info":{"title":"allowances.dev API","version":"1","description":"Utility allowance schedules of US housing authorities: one row per printed monthly amount, with the source document and page. The fields are those of the CSV tables."},"servers":[{"url":"https://api.allowances.dev"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/v1/states":{"get":{"operationId":"listStates","summary":"States in the dataset, with counts","responses":{"200":{"description":"List of states","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/states/{state}":{"get":{"operationId":"listAuthoritiesOfState","summary":"Authorities of one state","parameters":[{"name":"state","in":"path","required":true,"description":"Two-letter state code","schema":{"type":"string"},"example":"TX"}],"responses":{"200":{"description":"Authorities","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/authorities":{"get":{"operationId":"searchAuthorities","summary":"Find authorities by state, city, county or name","parameters":[{"name":"state","in":"query","required":false,"description":"Two-letter state code","schema":{"type":"string"},"example":"TX"},{"name":"city","in":"query","required":false,"description":"Text contained in the city","schema":{"type":"string"},"example":"Waco"},{"name":"county","in":"query","required":false,"description":"Text contained in the county","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Text contained in the authority name","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Text contained in the name, city, county, metro area or code","schema":{"type":"string"}}],"responses":{"200":{"description":"Authorities","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/authorities/{agency_id}":{"get":{"operationId":"getAuthority","summary":"One authority with its schedules and their source documents","parameters":[{"name":"agency_id","in":"path","required":true,"description":"HUD code of the authority","schema":{"type":"string"},"example":"TX010"}],"responses":{"200":{"description":"Authority","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/authorities/{agency_id}/schedules":{"get":{"operationId":"listSchedules","summary":"Schedules of one authority","parameters":[{"name":"agency_id","in":"path","required":true,"description":"HUD code of the authority","schema":{"type":"string"},"example":"TX010"}],"responses":{"200":{"description":"Schedules","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/authorities/{agency_id}/values":{"get":{"operationId":"getAuthorityValues","summary":"Amounts of one authority, optionally filtered","parameters":[{"name":"agency_id","in":"path","required":true,"description":"HUD code of the authority","schema":{"type":"string"},"example":"TX010"},{"name":"schedule_id","in":"query","required":false,"description":"Only this schedule","schema":{"type":"string"}},{"name":"program","in":"query","required":false,"description":"HCV, public housing, both, other","schema":{"type":"string"}},{"name":"utility","in":"query","required":false,"description":"Utility code, for example heating, cooking, water_heating, other_electric, water, sewer, trash (all codes: /v1/codes)","schema":{"type":"string"}},{"name":"fuel","in":"query","required":false,"description":"Fuel code, for example natural_gas, electric, bottled_gas, fuel_oil","schema":{"type":"string"}},{"name":"building_type","in":"query","required":false,"description":"Unit type code, for example single_family_detached, row_townhouse, apartment_unspecified","schema":{"type":"string"}},{"name":"bedrooms","in":"query","required":false,"description":"SRO, 0 to 9, or all","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Text contained in the area (place, provider area or development), any case","schema":{"type":"string"}},{"name":"variant","in":"query","required":false,"description":"Text contained in the variant, any case","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number, from 1. A page holds up to 2,000 rows before filtering; follow next_page until it is null.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Rows","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/schedules/{schedule_id}":{"get":{"operationId":"getSchedule","summary":"One schedule with its source documents","parameters":[{"name":"schedule_id","in":"path","required":true,"description":"Schedule id","schema":{"type":"string"},"example":"TX010-HCV-2025-10-01-McLennan"}],"responses":{"200":{"description":"Schedule","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/schedules/{schedule_id}/values":{"get":{"operationId":"getScheduleValues","summary":"Amounts of one schedule, optionally filtered","parameters":[{"name":"schedule_id","in":"path","required":true,"description":"Schedule id","schema":{"type":"string"},"example":"TX010-HCV-2025-10-01-McLennan"},{"name":"program","in":"query","required":false,"description":"HCV, public housing, both, other","schema":{"type":"string"}},{"name":"utility","in":"query","required":false,"description":"Utility code, for example heating, cooking, water_heating, other_electric, water, sewer, trash (all codes: /v1/codes)","schema":{"type":"string"}},{"name":"fuel","in":"query","required":false,"description":"Fuel code, for example natural_gas, electric, bottled_gas, fuel_oil","schema":{"type":"string"}},{"name":"building_type","in":"query","required":false,"description":"Unit type code, for example single_family_detached, row_townhouse, apartment_unspecified","schema":{"type":"string"}},{"name":"bedrooms","in":"query","required":false,"description":"SRO, 0 to 9, or all","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Text contained in the area (place, provider area or development), any case","schema":{"type":"string"}},{"name":"variant","in":"query","required":false,"description":"Text contained in the variant, any case","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number, from 1. A page holds up to 2,000 rows before filtering; follow next_page until it is null.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Rows","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/codes":{"get":{"operationId":"listCodes","summary":"Every code used in the data, with its meaning","responses":{"200":{"description":"Codes","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/downloads":{"get":{"operationId":"listDownloads","summary":"The full tables as files","responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}},"/v1/downloads/{file}":{"get":{"operationId":"downloadFile","summary":"Download one table (gzip CSV)","parameters":[{"name":"file","in":"path","required":true,"description":"File name from /v1/downloads","schema":{"type":"string"},"example":"values.csv.gz"}],"responses":{"200":{"description":"The file","content":{"application/gzip":{}}},"401":{"description":"Missing or wrong API key"},"404":{"description":"Not found"}}}}}}