Developer Documentation · Dataset Catalog

Dataset Catalog API

A single endpoint returns a documented 15-entry CMS and HHS-OIG catalog subset with available row-count observations, system timestamps, and FHIR endpoint references. No authentication required.

GET /api/datasets FHIR R4 API docs Badge embed docs

Quickstart

One request. Full catalog. No key required.

The endpoint returns a JSON array. No pagination — the full catalog (15 datasets) fits in a single response.

# List all datasets
curl -s https://fonteum.com/api/datasets | jq '.[0]'

# Count total rows across all datasets
curl -s https://fonteum.com/api/datasets | jq '[.[].row_count // 0] | add'

# Filter to FHIR-backed datasets only
curl -s https://fonteum.com/api/datasets \
  | jq '[.[] | select(.fhir_endpoint_if_applicable != null)]'

Sample response

JSON array. One entry per dataset.

[
  {
    "id": "cms-pos-facilities",
    "name": "CMS Provider of Services Facilities",
    "source": "CMS Provider of Services File",
    "source_url": "https://data.cms.gov/provider-characteristics/...",
    "last_refreshed_at": null,
    "last_observed_at": "2026-07-15T06:15:00.000Z",
    "timestamp_basis": "content_change",
    "evidence_status": "unproved",
    "row_count": 68211,
    "schema_url": "https://fonteum.com/api/fhir/Organization",
    "license": "US-Government-Works",
    "fhir_endpoint_if_applicable": "https://fonteum.com/api/fhir/Organization"
  },
  {
    "id": "oig-leie-exclusions",
    "name": "OIG LEIE Federal Exclusions",
    "source": "HHS OIG List of Excluded Individuals/Entities",
    "source_url": "https://oig.hhs.gov/exclusions/exclusions_list.asp",
    "last_refreshed_at": null,
    "last_observed_at": "2026-07-15T06:15:00.000Z",
    "timestamp_basis": "content_change",
    "evidence_status": "unproved",
    "row_count": 68055,
    "schema_url": "https://fonteum.com/docs/datasets",
    "license": "US-Government-Works",
    "fhir_endpoint_if_applicable": null
  }
  // ... 13 more entries
]

Field reference

Fields can be null or absent by dataset.

Field	Type	Description
`id`	`string`	Dataset slug — stable identifier, matches the slug used in /api/freshness and /llms.txt
`name`	`string`	Human-readable dataset name
`source`	`string`	Upstream federal source name (e.g. CMS Provider of Services File)
`source_url`	`string`	Canonical upstream data portal URL
`last_refreshed_at`	`string \| null`	ISO-8601 timestamp of the last proved row-count or content-hash change. A workflow run alone cannot advance it.
`last_observed_at`	`string \| null`	ISO-8601 timestamp of the latest snapshot-ledger insert. It may be unchanged or rejected and is not a workflow-success claim.
`timestamp_basis`	`"content_change"`	Declares that last_refreshed_at is change-backed, not job-run-backed.
`evidence_status`	`"content_change" \| "unproved" \| "error"`	Whether the timestamp is transition-backed, still lacks a proved transition, or could not be read safely.
`row_count`	`number \| null`	Live table row-count observation from Supabase. Null when the count cannot be read; it is not an upstream freshness signal.
`schema_url`	`string`	FHIR endpoint URL when the dataset is exposed via the FHIR R4 API; otherwise /docs/datasets.
`license`	`string`	SPDX license identifier. US-Government-Works for all CMS and HHS-OIG datasets.
`fhir_endpoint_if_applicable`	`string \| null`	Full FHIR endpoint URL for FHIR-backed datasets. Null for datasets not yet exposed via FHIR.

Refresh cadence

Federal publication cadence, not daily.

Publisher cadence is descriptive metadata, not proof that Fonteum loaded the latest release. When checked 2026-07-12, the serving data showed NPPES system date 2026-06-10, PECOS source date 2026-06-18, OIG LEIE source date 2026-05-08, supported Care Compare source date 2026-05-07, and PBJ work date 2025-06-30. Treat last_refreshed_at as the last proved content change and last_observed_at as the latest ledger insert; inspect the source-specific release date before relying on publisher currency. For programmatic monitoring, use /api/freshness which also includes SLA windows and status flags.

Caching

1-hour edge cache for the catalog response.

The response is cached at the edge for 1 hour (s-maxage=3600). Row counts are recomputed on each cold miss via a COUNT(*) against Supabase. That updates the table-count observation, not the date or contents of an upstream source release.