{"openapi":"3.1.0","info":{"title":"ECHO Provider API","version":"1.1.0","description":"Provider directory snapshot. Call providers to confirm services. Public access: 30 requests per minute per IP, 25 results per request. Partner policies are configured per key, with up to 200 results per request."},"servers":[{"url":"https://providers.echousing.org"}],"security":[{},{"PartnerKey":[]}],"paths":{"/health":{"get":{"operationId":"health","security":[],"responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}}}}}}}},"/v1/counties":{"get":{"operationId":"listCounties","responses":{"200":{"description":"Success","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"string","enum":["Chesterfield","Clarendon","Darlington","Dillon","Florence","Georgetown","Horry","Kershaw","Lee","Marion","Marlboro","Sumter","Williamsburg"]}}}}}}},"400":{"description":"Invalid filters or pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Malformed authorization or invalid, expired, revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Partner credits exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Access checks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/categories":{"get":{"operationId":"listCategories","responses":{"200":{"description":"Success","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"400":{"description":"Invalid filters or pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Malformed authorization or invalid, expired, revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Partner credits exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Access checks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/providers":{"get":{"operationId":"searchProviders","summary":"Search providers with organization name matches first","parameters":[{"name":"q","in":"query","description":"All words must match the name, address, counties, coverage notes or description. Punctuation and accents are ignored. Name matches rank first; descriptions include service exclusions.","schema":{"type":"string"}},{"name":"county","in":"query","description":"Canonical county name, case insensitive","schema":{"type":"string","enum":["Chesterfield","Clarendon","Darlington","Dillon","Florence","Georgetown","Horry","Kershaw","Lee","Marion","Marlboro","Sumter","Williamsburg"]}},{"name":"category","in":"query","description":"Curated service category","schema":{"type":"string","enum":["food","shelter","housing","transportation","health","recovery","employment","disability","family","veterans","legal-benefits","libraries"]}},{"name":"coverage","in":"query","description":"Include only providers with other coverage notes","schema":{"type":"string","enum":["outside"]}},{"name":"limit","in":"query","description":"Positive integer. Defaults to and is capped at 25 for public access or 200 for partners.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"offset","in":"query","description":"Number of matches to skip","schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0}}],"responses":{"200":{"description":"Success","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid filters or pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Malformed authorization or invalid, expired, revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Partner credits exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Access checks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/providers/{id}":{"get":{"operationId":"getProvider","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Success","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","snapshot"],"properties":{"data":{"$ref":"#/components/schemas/Provider"},"snapshot":{"$ref":"#/components/schemas/Snapshot"}}}}}},"400":{"description":"Invalid filters or pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Malformed authorization or invalid, expired, revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Partner credits exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Provider not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request limit reached","headers":{"X-RateLimit-Limit":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Public request quota.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Public quota reset, Unix milliseconds.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Access checks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"PartnerKey":{"type":"http","scheme":"bearer","description":"Optional Unkey partner key. Keep it on your server."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"Snapshot":{"type":"object","required":["date","source"],"properties":{"date":{"type":"string","format":"date","description":"Export date, not individual provider verification"},"source":{"type":"string"}}},"Category":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","enum":["food","shelter","housing","transportation","health","recovery","employment","disability","family","veterans","legal-benefits","libraries"]},"label":{"type":"string"}}},"Provider":{"type":"object","required":["id","name","address","lat","lng","counties","coverageNotes","categories","phone","website","details"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"address":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"details":{"type":["string","null"]},"counties":{"type":"array","items":{"type":"string","enum":["Chesterfield","Clarendon","Darlington","Dillon","Florence","Georgetown","Horry","Kershaw","Lee","Marion","Marlboro","Sumter","Williamsburg"]}},"coverageNotes":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string","enum":["food","shelter","housing","transportation","health","recovery","employment","disability","family","veterans","legal-benefits","libraries"]}}}},"SearchResponse":{"type":"object","required":["tier","total","limit","offset","snapshot","data"],"properties":{"tier":{"type":"string","enum":["public","partner"]},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":200},"offset":{"type":"integer","minimum":0},"snapshot":{"$ref":"#/components/schemas/Snapshot"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Provider"}}}}}}}