{
 "openapi": "3.1.0",
 "info": {
  "title": "HomeCareFinder static API",
  "version": "2026-10-20",
  "description": "Read-only static JSON. Medicare home health: CMS data ranked by CMS stars, never paid. Home care / assisted living / memory care: state licensing data, alphabetical, live for CA (California CDSS); TX coming soon. Costs: CareScout 2025 national, Texas and California medians (cited). Florida: coming 2027-01-01, no data published. The order of our lists can't be bought. Every provider in a list is placed by the same rule, and paying never adds anyone to a list, moves anyone up or down, or removes anyone. Misses return a JSON 404."
 },
 "servers": [
  {
   "url": "https://myhomecarefinder.com"
  }
 ],
 "paths": {
  "/api/index.json": {
   "get": {
    "operationId": "getIndex",
    "summary": "Endpoints and states",
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/states/{state}.json": {
   "get": {
    "operationId": "getState",
    "summary": "Cities in a state",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "2-letter code, lowercase"
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/cities/{state}/{city}.json": {
   "get": {
    "operationId": "getCity",
    "summary": "Ranked agencies in a city",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "city slug, e.g. san-antonio"
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/agencies/{prefix}.json": {
   "get": {
    "operationId": "getAgencyShard",
    "summary": "Agencies whose CMS Certification Number starts with this 2-digit prefix, keyed by CCN",
    "parameters": [
     {
      "name": "prefix",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/costs.json": {
   "get": {
    "operationId": "getCosts",
    "summary": "CareScout 2025 median costs, national and by state (null = not reported)",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/care-types.json": {
   "get": {
    "operationId": "getCareTypes",
    "summary": "Plain-language definitions of care types, who pays, cost keys",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/florida.json": {
   "get": {
    "operationId": "getFloridaStatus",
    "summary": "Florida coverage notice (coming 2027-01-01)",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/home-care/tx.json": {
   "get": {
    "operationId": "getHomeCareTexasStatus",
    "summary": "Texas home care: status coming_soon (listings not published yet)",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/assisted-living/tx.json": {
   "get": {
    "operationId": "getAssistedLivingTexasStatus",
    "summary": "Texas assisted living: status coming_soon (listings not published yet)",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/memory-care/tx.json": {
   "get": {
    "operationId": "getMemoryCareTexasStatus",
    "summary": "Texas memory care: status coming_soon (listings not published yet)",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/home-care/ca/{city}.json": {
   "get": {
    "operationId": "getHomeCareCityCA",
    "summary": "California Home Care Organizations in a city (CDSS file dated May 25, 2025)",
    "parameters": [
     {
      "name": "city",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/assisted-living/ca/{city}.json": {
   "get": {
    "operationId": "getAssistedLivingCityCA",
    "summary": "California licensed RCFEs (assisted living) in a city",
    "parameters": [
     {
      "name": "city",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found or coming_soon)"
     }
    }
   }
  },
  "/api/hospice/{state}.json": {
   "get": {
    "operationId": "getHospiceState",
    "summary": "Hospices in a state: city index plus smaller-city hospices, ranked by CMS family caregiver star rating",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found)"
     }
    }
   }
  },
  "/api/hospice/{state}/{city}.json": {
   "get": {
    "operationId": "getHospiceCity",
    "summary": "Medicare-certified hospices in a city, ranked by CMS family caregiver star rating (ties A-Z, unrated last)",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found)"
     }
    }
   }
  },
  "/api/nursing-homes/{state}.json": {
   "get": {
    "operationId": "getNursingHomeState",
    "summary": "Nursing homes in a state: city index plus smaller-city nursing homes, ranked by CMS overall star rating",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found)"
     }
    }
   }
  },
  "/api/nursing-homes/{state}/{city}.json": {
   "get": {
    "operationId": "getNursingHomeCity",
    "summary": "Nursing homes in a city, ranked by CMS overall star rating (ties A-Z, unrated last), with CMS flags",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "Not found (JSON body with status not_found)"
     }
    }
   }
  }
 }
}