REST API reference — Covelight Care developers

Basics

Base URL https://covelightcare.com. No key, no account, no OAuth.
JSON in and out. Call it from a server or a script: the API sends no CORS headers.
Every response is an envelope: data, then attribution (the source, the record’s retrieved_on date and the terms), then generated_at. The front door GET /api/v1 is the one plain object.
POST /api/v1/check takes an optional X-Client-Name header: your product’s name, for our counts of which tools use the API. It never changes a result; never put a person’s name in it.
Field meanings — tri-state values, dates, statuses — are in the data dictionary.

The envelope (from GET /api/v1/facilities/{license})

{
  "api_version": "v1",
  "data": "… (the endpoint’s own data)",
  "attribution": {
    "source": "California Department of Social Services, Community Care Licensing Division",
    "retrieved_on": "2026-09-13",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-09-24T01:02:54.163Z"
}

Errors

Status	When	How to recover
400	A parameter or body the endpoint does not accept. Unknown parameters are refused, never ignored, so a typo cannot quietly widen a result.	Read `error`: it names what was wrong and lists what is accepted. Fix the call and send it again.
404	No home with that license number is on the roster we hold.	Look the home up by name with `POST /api/v1/check`, which returns its license number or the candidates.
413	`POST /api/v1/check` only: a body far larger than any 100-home batch.	Send at most 100 homes per call.
429	Past the per-IP budget for that path.	Wait the number of seconds in `Retry-After`, then retry.
500	The server could not finish. Nothing was changed.	Retry after a minute. If it persists, write to support with the request.

Every error body is {"error": "…"}. Real ones, as the API sent them:

A sort parameter (none exists) → 400

Request

GET https://covelightcare.com/api/v1/facilities?county=Los%20Angeles&sort=price

Response · 400 · application/json

HTTP response

HTTP 400
content-type: application/json
cache-control: no-store

{
  "error": "No sort parameter exists: results always return in neutral alphabetical order, because no score, tier, or payment ever orders this list."
}

A need the API does not know → 400

Request

GET https://covelightcare.com/api/v1/facilities?needs=memory

Response · 400 · application/json

HTTP response

HTTP 400
content-type: application/json
cache-control: no-store

{
  "error": "Unknown need \"memory\". Accepted: wheelchair, dementia, hospice, bedridden."
}

A limit past the maximum → 400

Request

GET https://covelightcare.com/api/v1/facilities?limit=500

Response · 400 · application/json

HTTP response

HTTP 400
content-type: application/json
cache-control: no-store

{
  "error": "limit must be an integer between 1 and 100."
}

A license number not on the roster → 404

Request

GET https://covelightcare.com/api/v1/facilities/000000

Response · 404 · application/json

HTTP response

HTTP 404
content-type: application/json
cache-control: no-store

{
  "error": "No home with this license number is on the roster we hold."
}

A batch with no homes → 400

Request

POST https://covelightcare.com/api/v1/check
Content-Type: application/json

{
  "homes": []
}

Response · 400 · application/json

HTTP response

HTTP 400
content-type: application/json
cache-control: no-store

{
  "error": "check_homes could not read these inputs — homes: Too small: expected array to have >=1 items. Accepted inputs: homes, detail."
}

A body that is not JSON → 400

Request

POST https://covelightcare.com/api/v1/check
Content-Type: application/json

homes=191200037

Response · 400 · application/json

HTTP response

HTTP 400
content-type: application/json
cache-control: no-store

{
  "error": "The body must be JSON: {\"homes\": [\"license number or name\", …]}."
}

Request 121 inside one minute from one IP → 429

Request

GET https://covelightcare.com/api/v1/facilities?county=Alpine

Response · 429 · application/json

HTTP response

HTTP 429
content-type: application/json
cache-control: no-store
retry-after: 60

{
  "error": "Too many requests. Please slow down and try again shortly."
}

Rate limits

Path	Requests per minute, per IP
`/api/v1/*`	120
`POST /api/v1/check`	30
`/mcp` (the MCP server)	60

One request is one unit, however many homes it carries: checking 100 homes in one batch costs what one costs, so batch instead of looping. Each budget is counted on its own. Counters are kept per server instance, so treat these numbers as the budget to stay under. Past it, the answer is 429 with Retry-After (see the example above).

Pagination

GET /api/v1/facilities pages with limit (default 50, at most 100) and offset (at most 20000). data.total counts every match; ask for offset + limit until you reach it.
GET /api/v1/facilities/{license}/reports and GET /api/v1/guides return the whole list in one response.
POST /api/v1/check takes 1–100 homes per call and answers them in the order sent.

Caching

Endpoint	`Cache-Control`, as sent
`GET /api/v1`	`public, s-maxage=3600, stale-while-revalidate=86400`
`GET /api/v1/facilities`	`public, s-maxage=300, stale-while-revalidate=300`
`GET /api/v1/facilities/{license}`	`public, s-maxage=300, stale-while-revalidate=300`
`GET /api/v1/facilities/{license}/reports`	`public, s-maxage=3600, stale-while-revalidate=86400`
`GET /api/v1/guides`	`public, s-maxage=3600, stale-while-revalidate=86400`
`POST /api/v1/check`	`no-store`

Reads may be served from our CDN for up to the s-maxage shown; the batch check is never cached. How old the record is, is a separate question: read attribution.retrieved_on and each fact’s confirmed_on.

Versioning

Every envelope says "api_version": "v1". Within v1, changes are additive: new endpoints and new fields may appear; no field is removed or changes meaning.
Ignore fields you do not know. They are additions, never a change to the ones you read.
Build on /api/v1 only. The site’s own endpoints — /api/facilities/{license}, /api/facilities/suggest, /api/facilities/in-bounds and /api/facilities/all-points — are shaped by its pages, unversioned, and may change without notice; their nulls carry no tri-state promise.
Changes are listed in the changelog.

Endpoints

GET/api/v1

Machine-readable front door: endpoint inventory, contract links, honesty lines.

curl "https://covelightcare.com/api/v1"

const res = await fetch("https://covelightcare.com/api/v1");
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
console.log(Object.keys(body.endpoints));

import requests

res = requests.get("https://covelightcare.com/api/v1", timeout=30)
body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code}: {body['error']}")
print(list(body["endpoints"]))

The request, as sent

GET https://covelightcare.com/api/v1

Response · 200 · application/json

HTTP response

HTTP 200
content-type: application/json
cache-control: public, s-maxage=3600, stale-while-revalidate=86400

{
  "api_version": "v1",
  "description": "Free read API over the California state record of licensed elder-care homes (RCFEs). Facts carry provenance; consequential fields are tri-state (\"true\" | \"false\" | \"not_on_file\" — \"not on file\" is a statement about the record, never a \"no\"). Availability is never in this data; a family asks the home by phone, and each facility_page link carries the home's phone number and state record.",
  "endpoints": {
    "list": "https://covelightcare.com/api/v1/facilities?county=&city=&needs=&limit=&offset=",
    "facility": "https://covelightcare.com/api/v1/facilities/{license_number}",
    "reports": "https://covelightcare.com/api/v1/facilities/{license_number}/reports",
    "guides": "https://covelightcare.com/api/v1/guides",
    "batch_check": "POST https://covelightcare.com/api/v1/check {\"homes\": [\"license number or name\", …]} (up to 100)"
  },
  "mcp": {
    "url": "https://covelightcare.com/mcp",
    "transport": "streamable-http (stateless, JSON responses, no auth)",
    "documentation": "https://covelightcare.com/developers/mcp"
  },
  "openapi": "https://covelightcare.com/openapi.json",
  "documentation": "https://covelightcare.com/developers",
  "terms": "https://covelightcare.com/developers#terms",
  "attribution": "California Department of Social Services, Community Care Licensing Division",
  "ordering": "Lists return neutral alphabetical order. No sort parameter exists: no score, tier, or payment ever orders any list here."
}

Responses

200 — Endpoint inventory with documentation, terms, and attribution links.

GET/api/v1/facilities

List licensed homes (directory vocabulary, incl. probationary — shown as fact).

Neutral alphabetical order (facility name, then license number). There is no sort parameter: no score, tier, or payment ever orders this list. Unknown parameters return 400 rather than being silently ignored, so an agent that believes it filtered never receives an unfiltered set.

Name	In	Type	Required	What it means
`county`	query	`string`	no	County name, case-insensitive exact match (e.g. "Los Angeles").
`city`	query	`string`	no	City name, case-insensitive exact match.
`needs`	query	`string`	no	Comma-separated care-need keys, ANDed: wheelchair, dementia, hospice, bedridden. A need matches only a home whose license explicitly carries the state clearance (a "not on file" record never matches — and is never presented as a "no"). A clearance under a correction review reads "not_on_file" and does not match, as on the facility page and in the MCP tools (within five minutes of the review opening: this list is CDN-cached for five minutes).
`limit`	query	`integer 1 to 100`	no	Default 50.
`offset`	query	`integer 0 to 20000`	no	Default 0.

curl "https://covelightcare.com/api/v1/facilities?county=Los%20Angeles&needs=dementia,wheelchair&limit=2"

const res = await fetch("https://covelightcare.com/api/v1/facilities?county=Los%20Angeles&needs=dementia,wheelchair&limit=2");
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
console.log(`${body.data.total} homes; next page: offset=${body.data.offset + body.data.limit}`);
for (const f of body.data.facilities) console.log(f.license_number, f.name.value, f.clearances.dementia.value);

import requests

res = requests.get("https://covelightcare.com/api/v1/facilities", params={"county": "Los Angeles", "needs": "dementia,wheelchair", "limit": "2"}, timeout=30)
body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code}: {body['error']}")
print(body["data"]["total"], "homes; next page: offset =", body["data"]["offset"] + body["data"]["limit"])
for f in body["data"]["facilities"]:
    print(f["license_number"], f["name"]["value"], f["clearances"]["dementia"]["value"])

The request, as sent

GET https://covelightcare.com/api/v1/facilities?county=Los%20Angeles&needs=dementia,wheelchair&limit=2

Response · 200 · application/json

HTTP response

HTTP 200
content-type: application/json
cache-control: public, s-maxage=300, stale-while-revalidate=300

{
  "api_version": "v1",
  "data": {
    "facilities": [
      {
        "license_number": "197610547",
        "name": {
          "value": "1ST CLASS BOARD AND CARE",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:facility_name"
        },
        "licensed_name": {
          "value": "1ST CLASS BOARD AND CARE",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:facility_name"
        },
        "facility_type": {
          "value": "RESIDENTIAL CARE ELDERLY",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:facility_type"
        },
        "license_status": {
          "value": "Licensed",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:license_status"
        },
        "license_status_live": {
          "value": null,
          "source_class": "state",
          "confirmed_on": null,
          "next_due": null,
          "ref": "roster:license_status_live"
        },
        "on_probation": {
          "value": "false",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:on_probation"
        },
        "address": {
          "value": {
            "street": "9524 ENCINO AVE",
            "city": "NORTHRIDGE",
            "county": "LOS ANGELES",
            "zip": "91325"
          },
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:address"
        },
        "location": {
          "value": {
            "latitude": 34.24389493,
            "longitude": -118.5155523
          },
          "source_class": "machine_extracted",
          "confirmed_on": null,
          "next_due": null,
          "ref": "derived:geocode"
        },
        "capacity": {
          "value": 6,
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:bed_count"
        },
        "phone": {
          "value": "(323) 408-9600",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:phone"
        },
        "licensee": {
          "value": "7 TWO 5 INC",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:licensee"
        },
        "operating_since_year": {
          "value": 2024,
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:license_first_date"
        },
        "clearances": {
          "dementia": {
            "value": "true",
            "source_class": "state",
            "confirmed_on": "2026-09-13",
            "next_due": null,
            "ref": "roster:dementia_certified"
          },
          "hospice": {
            "value": "true",
            "source_class": "state",
            "confirmed_on": "2026-09-13",
            "next_due": null,
            "ref": "roster:hospice_waiver"
          },
          "non_ambulatory": {
            "value": "true",
            "source_class": "state",
            "confirmed_on": "2026-09-13",
            "next_due": null,
            "ref": "roster:non_ambulatory_approved"
          },
          "bedridden": {
            "value": "true",
            "source_class": "state",
            "confirmed_on": "2026-09-13",
            "next_due": null,
            "ref": "roster:bedridden_waiver"
          }
        },
        "alw_participation": {
          "value": "not_on_file",
          "source_class": "state",
          "confirmed_on": "2026-08-09",
          "next_due": null,
          "ref": "roster:alw_participating"
        },
        "service_designations": {
          "value": [
            "983 - RCFE / DEMENTIA"
          ],
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:client_served"
        },
        "last_state_visit": {
          "value": "2026-08-15",
          "source_class": "state",
          "confirmed_on": "2026-09-13",
          "next_due": null,
          "ref": "roster:last_visit"
        },
        "disputes": [],
        "links": {
          "facility_page": "https://covelightcare.com/facility/1st-class-board-and-care-197610547",
          "corrections": "https://covelightcare.com/corrections?lic=197610547"
        }
      }
    ],
    "total": 887,
    "limit": 2,
    "offset": 0,
    "order": "name_asc"
  },
  "attribution": {
    "source": "California Department of Social Services, Community Care Licensing Division",
    "retrieved_on": "2026-09-23",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-09-24T01:02:54.133Z"
}

Shortened for this page (… marks each cut): data.facilities: 1 of 2 shown.

Responses

200 — Envelope whose data carries facilities[], total, limit, offset, and the stated order.
400 — Malformed or unknown parameter. Unknown parameters fail closed rather than being ignored; sort/order/rank get the specific answer that no ranking parameter exists.
429 — Per-IP window exceeded. Wait the Retry-After seconds, then retry. Budgets: 120 req/min for /api/v1/*, 30 for POST /api/v1/check.

GET/api/v1/facilities/{license}

One home's full v1 record.

Serves the stored state roster plus the last stored live CDSS status with its checked-on date. An API call never triggers a live state lookup.

Name	In	Type	Required	What it means
`license`	path	`string`	yes	CDSS facility license number.

curl "https://covelightcare.com/api/v1/facilities/191200037"

const res = await fetch("https://covelightcare.com/api/v1/facilities/191200037");
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
const home = body.data;
console.log(home.name.value, home.license_status.value, "as of", home.license_status.confirmed_on);
for (const [need, fact] of Object.entries(home.clearances)) console.log(need, fact.value);

import requests

res = requests.get("https://covelightcare.com/api/v1/facilities/191200037", timeout=30)
body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code}: {body['error']}")
home = body["data"]
print(home["name"]["value"], home["license_status"]["value"], "as of", home["license_status"]["confirmed_on"])
for need, fact in home["clearances"].items():
    print(need, fact["value"])

The request, as sent

GET https://covelightcare.com/api/v1/facilities/191200037

Response · 200 · application/json

HTTP response

HTTP 200
content-type: application/json
cache-control: public, s-maxage=300, stale-while-revalidate=300

{
  "api_version": "v1",
  "data": {
    "license_number": "191200037",
    "name": {
      "value": "REGENCY PARK OAK KNOLL",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:facility_name"
    },
    "licensed_name": {
      "value": "REGENCY PARK OAK KNOLL",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:facility_name"
    },
    "facility_type": {
      "value": "RESIDENTIAL CARE ELDERLY",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:facility_type"
    },
    "license_status": {
      "value": "Licensed",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:license_status"
    },
    "license_status_live": {
      "value": null,
      "source_class": "state",
      "confirmed_on": null,
      "next_due": null,
      "ref": "roster:license_status_live"
    },
    "on_probation": {
      "value": "false",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:on_probation"
    },
    "address": {
      "value": {
        "street": "255 SOUTH OAK KNOLL",
        "city": "PASADENA",
        "county": "LOS ANGELES",
        "zip": "91101"
      },
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:address"
    },
    "location": {
      "value": {
        "latitude": 34.141582,
        "longitude": -118.135185
      },
      "source_class": "machine_extracted",
      "confirmed_on": null,
      "next_due": null,
      "ref": "derived:geocode"
    },
    "capacity": {
      "value": 206,
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:bed_count"
    },
    "phone": {
      "value": "(626) 578-1551",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:phone"
    },
    "licensee": {
      "value": "REGENCY PARK, SOUTH OAK KNOLL",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:licensee"
    },
    "operating_since_year": {
      "value": 1987,
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:license_first_date"
    },
    "clearances": {
      "dementia": {
        "value": "true",
        "source_class": "state",
        "confirmed_on": "2026-09-13",
        "next_due": null,
        "ref": "roster:dementia_certified"
      },
      "hospice": {
        "value": "not_on_file",
        "source_class": "state",
        "confirmed_on": "2026-09-13",
        "next_due": null,
        "ref": "roster:hospice_waiver"
      },
      "non_ambulatory": {
        "value": "true",
        "source_class": "state",
        "confirmed_on": "2026-09-13",
        "next_due": null,
        "ref": "roster:non_ambulatory_approved"
      },
      "bedridden": {
        "value": "not_on_file",
        "source_class": "state",
        "confirmed_on": "2026-09-13",
        "next_due": null,
        "ref": "roster:bedridden_waiver"
      }
    },
    "alw_participation": {
      "value": "not_on_file",
      "source_class": "state",
      "confirmed_on": "2026-08-09",
      "next_due": null,
      "ref": "roster:alw_participating"
    },
    "service_designations": {
      "value": [
        "983 - RCFE / DEMENTIA"
      ],
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:client_served"
    },
    "last_state_visit": {
      "value": "2026-04-06",
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "roster:last_visit"
    },
    "disputes": [],
    "links": {
      "facility_page": "https://covelightcare.com/facility/regency-park-oak-knoll-191200037",
      "corrections": "https://covelightcare.com/corrections?lic=191200037"
    },
    "state_documents": {
      "value": {
        "count": 15,
        "since_year": "2022",
        "latest_date": "2026-04-06"
      },
      "source_class": "state",
      "confirmed_on": "2026-09-13",
      "next_due": null,
      "ref": "derived:state_documents"
    }
  },
  "attribution": {
    "source": "California Department of Social Services, Community Care Licensing Division",
    "retrieved_on": "2026-09-13",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-09-24T01:02:54.163Z"
}

Responses

200 — Envelope whose data is the Facility record (detail adds state_documents).
404 — No home with this license number on the roster we hold.
429 — Per-IP window exceeded. Wait the Retry-After seconds, then retry. Budgets: 120 req/min for /api/v1/*, 30 for POST /api/v1/check.

GET/api/v1/facilities/{license}/reports

The home's dated state documents, newest first.

Documents are listed newest first, each with a stable ref and, where the state publishes a stable address for it, a url (null for every document today). The home's record on the state's site, where every listed document can be read, is state_record_url. Narrative content stays behind explicit request, the same as on the site; the MCP tool get_state_documents returns the transcribed text.

Name	In	Type	Required	What it means
`license`	path	`string`	yes	—

curl "https://covelightcare.com/api/v1/facilities/191200037/reports"

const res = await fetch("https://covelightcare.com/api/v1/facilities/191200037/reports");
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
console.log("Read them at", body.data.state_record_url);
for (const r of body.data.reports) console.log(r.date, r.title);

import requests

res = requests.get("https://covelightcare.com/api/v1/facilities/191200037/reports", timeout=30)
body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code}: {body['error']}")
print("Read them at", body["data"]["state_record_url"])
for r in body["data"]["reports"]:
    print(r["date"], r["title"])

The request, as sent

GET https://covelightcare.com/api/v1/facilities/191200037/reports

Response · 200 · application/json

HTTP response

HTTP 200
content-type: application/json
cache-control: public, s-maxage=3600, stale-while-revalidate=86400

{
  "api_version": "v1",
  "data": {
    "license_number": "191200037",
    "state_record_url": "https://www.ccld.dss.ca.gov/carefacilitysearch/FacDetail/191200037",
    "reports": [
      {
        "ref": "doc:BA58AF735DBD664A88258DD7007E6775",
        "control_number": null,
        "source_class": "state",
        "date": "2026-04-06",
        "type": "Inspection",
        "title": "FACILITY EVALUATION REPORT",
        "url": null
      },
      {
        "ref": "doc:A322435E39D319C688258D86006DB500",
        "control_number": null,
        "source_class": "state",
        "date": "2025-07-15",
        "type": "Other",
        "title": "FACILITY EVALUATION REPORT",
        "url": null
      }
    ],
    "total": 15
  },
  "attribution": {
    "source": "California Department of Social Services, Community Care Licensing Division",
    "retrieved_on": "2026-09-23",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-09-24T01:02:54.172Z"
}

Shortened for this page (… marks each cut): data.reports: 2 of 15 shown.

Responses

200 — Envelope whose data carries the report list.
404 — No home with this license number on the roster we hold.
429 — Per-IP window exceeded. Wait the Retry-After seconds, then retry. Budgets: 120 req/min for /api/v1/*, 30 for POST /api/v1/check.

GET/api/v1/guides

The guide corpus as titled resources (our editorial, attributed to us).

curl "https://covelightcare.com/api/v1/guides"

const res = await fetch("https://covelightcare.com/api/v1/guides");
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
for (const g of body.data.guides) console.log(g.title, g.url);

import requests

res = requests.get("https://covelightcare.com/api/v1/guides", timeout=30)
body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code}: {body['error']}")
for g in body["data"]["guides"]:
    print(g["title"], g["url"])

The request, as sent

GET https://covelightcare.com/api/v1/guides

Response · 200 · application/json

HTTP response

HTTP 200
content-type: application/json
cache-control: public, s-maxage=3600, stale-while-revalidate=86400

{
  "api_version": "v1",
  "data": {
    "guides": [
      {
        "slug": "paying-for-care-in-california",
        "title": "Paying for care in California",
        "description": "Compare the full monthly cost, understand payment options, and find the right person to ask about benefits.",
        "url": "https://covelightcare.com/guides/paying-for-care-in-california",
        "published_on": "2026-07-05",
        "reviewed_on": "2026-07-05"
      },
      {
        "slug": "rcfe-vs-assisted-living-vs-snf",
        "title": "RCFE vs. assisted living vs. skilled nursing",
        "description": "What California’s care-home terms actually mean, who licenses each, and what Medicare and Medi-Cal do — and don’t — pay for.",
        "url": "https://covelightcare.com/guides/rcfe-vs-assisted-living-vs-snf",
        "published_on": "2026-07-05",
        "reviewed_on": "2026-07-05"
      }
    ],
    "total": 11
  },
  "attribution": {
    "source": "Covelight Care (checked against California Department of Social Services records)",
    "retrieved_on": "2026-07-05",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-09-24T01:02:54.173Z"
}

Shortened for this page (… marks each cut): data.guides: 2 of 11 shown.

Responses

200 — Envelope whose data lists the guides with URLs and review dates.
429 — Per-IP window exceeded. Wait the Retry-After seconds, then retry. Budgets: 120 req/min for /api/v1/*, 30 for POST /api/v1/check.

POST/api/v1/check

Batch check: up to 100 California care homes by name or license number, in one call.

The REST twin of the MCP tool check_homes (same function, same output inside the v1 envelope). Each entry resolves exact license -> exact name -> fuzzy did-you-mean; a name that fits more than one license comes back ambiguous WITH candidates, never a guess; a miss is not_found. Each matched home carries dated license status, capacity, tri-state clearances, the price figure with its kind (the home’s own listed rate, or a labeled estimate with its range), Medi-Cal ALW with the list date, the state record’s size with the fairness sentence, and its canonical page + Markdown twin links. Results come back in the order given, compact by default; send detail: true for each home’s full record. Budget: 30 requests/min/IP — one request is one unit, however many homes it carries.

Name	In	Type	Required	What it means
`X-Client-Name`	header	`string (at most 60 chars)`	no	Your product’s name, for our counts of which assistants use the API. Never a person’s name; it never changes a result.

Request body (JSON)

Name	Type	Required	What it means
`homes`	`list of string (3 to 200 chars) (1 to 100 items)`	yes	1 to 100 California care homes, each a license number or a name as written on a list (3–200 characters). Add the city to a name to narrow it. Example: ["197609456", "Sunrise of Pasadena"].
`detail`	`true or false`	no	true adds each home’s full record (address, phone, dated sentences, sources) as `record`. Default false (compact). Example: true.

curl -X POST "https://covelightcare.com/api/v1/check" \
  -H "Content-Type: application/json" \
  -H "X-Client-Name: your-product" \
  -d '{"homes":["191200037","Sunrise","Zzqx Nothing"]}'

const res = await fetch("https://covelightcare.com/api/v1/check", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Client-Name": "your-product" },
  body: JSON.stringify({"homes":["191200037","Sunrise","Zzqx Nothing"]}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
for (const r of body.data.results) {
  console.log(r.input, r.status, r.home?.name ?? r.candidates.map((c) => c.name).join(" / "));
}

import requests

res = requests.post("https://covelightcare.com/api/v1/check", json={"homes": ["191200037", "Sunrise", "Zzqx Nothing"]}, headers={"X-Client-Name": "your-product"}, timeout=30)
body = res.json()
if not res.ok:
    raise SystemExit(f"{res.status_code}: {body['error']}")
for r in body["data"]["results"]:
    print(r["input"], r["status"], r["home"]["name"] if r["home"] else [c["name"] for c in r["candidates"]])

The request, as sent

POST https://covelightcare.com/api/v1/check
Content-Type: application/json
X-Client-Name: your-product

{
  "homes": [
    "191200037",
    "Sunrise",
    "Zzqx Nothing"
  ]
}

Response · 200 · application/json

HTTP response

HTTP 200
content-type: application/json
cache-control: no-store

{
  "api_version": "v1",
  "data": {
    "results": [
      {
        "input": "191200037",
        "status": "matched",
        "home": {
          "license_number": "191200037",
          "name": "Regency Park Oak Knoll",
          "licensed_name": "REGENCY PARK OAK KNOLL",
          "city": "Pasadena",
          "county": "Los Angeles",
          "license_status": "Licensed",
          "license_closed": false,
          "status_as_of": "2026-09-13",
          "beds": 206,
          "size_words": "Large community",
          "clearances": {
            "dementia": "true",
            "hospice": "not_on_file",
            "non_ambulatory": "true",
            "bedridden": "not_on_file",
            "as_of": "2026-09-13",
            "license_closed": false,
            "closed_note": null
          },
          "medi_cal_alw": {
            "value": "not_on_file",
            "line": "This home is not on the DHCS participation list dated August 9, 2026. Ask the program about current options.",
            "scope": "The waiver pays for care services, not room and board.",
            "list_as_of": "2026-08-09",
            "license_closed": false,
            "closed_note": null
          },
          "price": {
            "kind": "home_listed",
            "is_this_homes_own_rate": true,
            "monthly_usd": 5950,
            "likely_range_usd": null,
            "line": "Listed by the home on Seniorly · September 9, 2026"
          },
          "state_record": {
            "documents_on_file": 15,
            "latest_visit_date": "2026-04-06",
            "type_a_citations": 1,
            "type_b_citations": 3,
            "tallies_since_year": 1987
          },
          "page": "https://covelightcare.com/facility/regency-park-oak-knoll-191200037",
          "markdown": "https://covelightcare.com/facility/regency-park-oak-knoll-191200037.md"
        },
        "candidates": []
      },
      {
        "input": "Sunrise",
        "status": "ambiguous",
        "home": null,
        "candidates": [
          {
            "license_number": "15601324",
            "name": "Sunrise Care Home",
            "licensed_name": "SUNRISE CARE HOME",
            "city": "San Lorenzo",
            "county": "Alameda",
            "address": "1447 Via Lucas",
            "beds": 6,
            "license_status": "Licensed",
            "links": {
              "page": "https://covelightcare.com/facility/sunrise-care-home-15601324",
              "markdown": "https://covelightcare.com/facility/sunrise-care-home-15601324.md",
              "state_record": "https://www.ccld.dss.ca.gov/carefacilitysearch/FacDetail/15601324",
              "corrections": "https://covelightcare.com/corrections?lic=15601324"
            }
          },
          {
            "license_number": "306005651",
            "name": "Sunrise Garden",
            "licensed_name": "SUNRISE GARDEN",
            "city": "Laguna Niguel",
            "county": "Orange",
            "address": "29751 Ana Maria Lane",
            "beds": 6,
            "license_status": "Licensed",
            "links": {
              "page": "https://covelightcare.com/facility/sunrise-garden-306005651",
              "markdown": "https://covelightcare.com/facility/sunrise-garden-306005651.md",
              "state_record": "https://www.ccld.dss.ca.gov/carefacilitysearch/FacDetail/306005651",
              "corrections": "https://covelightcare.com/corrections?lic=306005651"
            }
          }
        ]
      },
      {
        "input": "Zzqx Nothing",
        "status": "not_found",
        "home": null,
        "candidates": []
      }
    ],
    "counts": {
      "given": 3,
      "duplicates_merged": 0,
      "matched": 1,
      "ambiguous": 1,
      "not_found": 1
    },
    "honesty": {
      "order": "In the order you gave them. Nothing here is ranked.",
      "neutrality": "No home pays to appear here. Nothing on this page is ranked by quality, popularity or payment.",
      "never_in_this_data": "No website — including this one — knows which homes have an open bed today. Openings change daily and live only inside each home. That is what the phone call is for.",
      "fairness_note": "A citation does not make a home unsafe, and an empty file does not make a home good."
    },
    "data_dates": {
      "state_record_loaded_on": "2026-09-13",
      "alw_list_as_of": "2026-08-09"
    },
    "display": "Checked 3 homes against the CDSS licensing record: 1 matched, 1 need a choice, 1 not found.\n\n**[Regency Park Oak Knoll](https://covelightcare.com/facility/regency-park-oak-knoll-191200037)** — Pasadena, Los Angeles County · Large community, licensed for 206 ·…"
  },
  "attribution": {
    "source": "California Department of Social Services, Community Care Licensing Division",
    "retrieved_on": "2026-09-13",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-09-24T01:02:54.173Z"
}

Shortened for this page (… marks each cut): data.results[1].candidates: 2 of 4 shown; data.display: shortened.

Responses

200 — Envelope whose data is the CheckResult.
400 — Malformed or unknown parameter. Unknown parameters fail closed rather than being ignored; sort/order/rank get the specific answer that no ranking parameter exists.
429 — Per-IP window exceeded. Wait the Retry-After seconds, then retry. Budgets: 120 req/min for /api/v1/*, 30 for POST /api/v1/check.

POST/mcp

The remote MCP server (Streamable HTTP, stateless, JSON responses, no auth).

JSON-RPC 2.0 over HTTP POST, per the Model Context Protocol. Tools: find_homes, check_homes, get_home, get_state_documents, compare_homes, homes_near_hospital, explain_care_topic, start_family_request, and search and fetch (OpenAI's compatibility pair) — each lists its input and output schema in tools/list. Point an MCP client at https://covelightcare.com/mcp. Both protocol eras: the 2025 initialize handshake and 2026-07-28 (server/discover, per-request _meta). GET and DELETE answer 405: there is no stream and no session to hold. Budget: 60 requests/min per caller; over it, 429 with Retry-After. Guide: https://covelightcare.com/developers#mcp

This is the MCP server. Its tools, calls and errors: MCP server reference.

Responses

200 — A JSON-RPC 2.0 response.
405 — Only POST (and OPTIONS) are served.
429 — Per-IP window exceeded. Wait the Retry-After seconds, then retry. Budgets: 120 req/min for /api/v1/*, 30 for POST /api/v1/check.

Examples captured 2026-09-24 by running each call against Covelight’s code and a copy of its database, then shortened where marked. The record changes with each load, so values you get may differ.