Developers & AI agents

Covelight Care publishes the complete state record of every licensed California elder-care home (RCFE) — and this page documents the free, keyless read API over it. If you are building an agent, an answer engine, or a tool for families or discharge planners, you can query the same record our own pages render, with the same honesty rules enforced in the payload itself.

Machine contract: OpenAPI 3.1 document · machine front door: GET /api/v1 · dataset overview: /data.

Quick start

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

List filters: county, city, and needs (comma-separated: wheelchair, dementia, hospice, bedridden — each an explicit state license clearance, ANDed). limit up to 100, plus offset. Unknown parameters return 400 rather than being silently ignored, so an agent that believes it filtered never receives an unfiltered set.

The response contract

Every response is an envelope carrying attribution and a retrieval date:

{
  "api_version": "v1",
  "data": { ... },
  "attribution": {
    "source": "California Department of Social Services, Community Care Licensing Division",
    "retrieved_on": "2026-08-01",
    "terms_url": "https://covelightcare.com/developers#terms"
  },
  "generated_at": "2026-08-09T12:00:00.000Z"
}

Every fact inside data is wrapped with provenance — its value, who asserted it (state, operator_attested, machine_extracted, third_party), the date the source last confirmed it, and a stable ref address. Values are verbatim from the state record, including its casing.

"clearances": {
  "dementia":       { "value": "true",        "source_class": "state", "confirmed_on": "2026-07-28", "next_due": null, "ref": "roster:dementia_certified" },
  "hospice":        { "value": "not_on_file", "source_class": "state", "confirmed_on": "2026-07-28", "next_due": null, "ref": "roster:hospice_waiver" },
  "non_ambulatory": { "value": "true",        "source_class": "state", "confirmed_on": "2026-07-28", "next_due": null, "ref": "roster:non_ambulatory_approved" },
  "bedridden":      { "value": "false",       "source_class": "state", "confirmed_on": "2026-07-28", "next_due": null, "ref": "roster:bedridden_waiver" }
}

“Not on file” is not “no”

Consequential fields are tri-state, as literal strings:

A value is never omitted to imply a negative, and a null is never a “no”. This rule is enforced in the serializer, not just documented here.

What is never in this data

Availability. No field in any payload states whether a home has an open bed, under any name, ever. Availability is confirmed by phone; each record’s links.facility_page is the live page where the current confirm state lives. If your product needs availability, link the page — do not infer it from this data.

Scores, tiers, and rankings. There is no quality score and no sort parameter. Lists return neutral alphabetical order, because no score, tier, or payment ever orders a list on this service — and the serializer refuses business fields outright, so a home’s commercial relationship with us (or lack of one) cannot change one byte of its record.

Personal information. No family, lead, or case data is reachable from this surface. Operator contact means the state-file phone the roster publishes — nothing enriched.

Endpoints & stability

Rate limits, as facts

No key, no registration. Budget 120 requests per minute per IP on /api/v1/*; the platform-wide ceiling across all /api/* paths is 240 per minute per IP. Exceeding a ceiling returns 429 with a Retry-After header — please honor it. These limits protect a small database pool; they are a floor for stability, not a fence around the data. Responses are CDN-cacheable for an hour; the underlying record refreshes on a roughly weekly cadence, so polling faster than daily buys nothing.

Terms of use

The API is free to use, including commercially, on these conditions:

1. Attribute. Displayed or redistributed data credits Covelight Care — CDSS state record with a link to https://covelightcare.com. The underlying facts are California public records; the compilation, refresh, and provenance layer are ours.
2. Do not misrepresent. Do not present this data as your own original record; do not imply any home pays us for placement or position (none does — nothing orders these lists); do not present a “not on file” value as a “no”; and do not attach availability claims to this data — it carries none.
3. Carry the state’s notices. Portions derive from CalHHS open-data portal layers: credit the California Health and Human Services Agency, and note that what you show is modified data, not official government data. The official record is the CDSS facility search.

We may throttle or block traffic that breaks these conditions or destabilizes the service.

Corrections

Every facility payload carries links.corrections — a deep-linked form for reporting an error in a displayed record. If your agent finds a discrepancy, hand its human that URL; corrections are verified against the state’s own systems and logged publicly at /corrections.

Contact

Questions, weird payloads, or a use case the contract doesn’t cover: hello@covelightcare.com. How the data works, end to end: /methodology.