{ "openapi": "3.0.3", "info": { "title": "Fonteum API", "version": "1.6.0", "description": "Fonteum provides programmatic access to supported public records across healthcare, federal procurement, sanctions and watchlists, enforcement, and corporate and securities records. Provenance coverage varies by endpoint and source: supported responses identify available source, date, methodology, and limitation fields, which can be null. A snapshot digest or attestation is not a signature on an individual fact.\n\nTry the live read-only sample with `Authorization: Bearer fnt_DEMO_PUBLIC_V1` (20/minute and 100/day per trusted client). For account-specific limits, create a developer account at https://fonteum.com/account/signup. API keys are shown once in the account dashboard and stored only as hashes.", "x-product-name": "Fonteum", "contact": { "name": "Fonteum API", "email": "api@fonteum.com", "url": "https://fonteum.com/data" }, "license": { "name": "Fonteum Editorial Policy", "url": "https://fonteum.com/editorial-policy" } }, "servers": [ { "url": "https://fonteum.com/api/v1", "description": "Production v1" } ], "tags": [ { "name": "Health", "description": "Service health and available source-timing observations." }, { "name": "Billing", "description": "Browser/account-session Checkout discovery and creation. This is not a Bearer-authenticated metered data endpoint." }, { "name": "Integrity", "description": "Public append-only chain inspection and cryptographic re-check endpoints." }, { "name": "Specialties", "description": "Medical specialty supply data (NPPES + Census)." }, { "name": "States", "description": "Per-state coverage rollups." }, { "name": "Providers", "description": "Single-provider lookup." }, { "name": "Methodology", "description": "Dataset methodology metadata." }, { "name": "Sources", "description": "Registered public-source families with authority, tier, publisher cadence, and official URL. Provenance fields are source-specific and can be null." }, { "name": "Bulk", "description": "Manifest-led public bulk downloads. Only files listed in the manifest are delivered in the named format." }, { "name": "Entity Graph", "description": "Published identifier crosswalks and entity-resolution links." }, { "name": "Quality", "description": "Fonteum data-quality scorecard, not facility-level quality ratings." }, { "name": "Search", "description": "Published semantic provider search using Server-Sent Events." }, { "name": "Audit Pack", "description": "Compliance artifacts for registered datasets. Available packs can include versioned methodology, field maps, reproducibility notes, limitations, change history, and PDF or JSON downloads." }, { "name": "Evidence Query", "description": "Natural-language Q&A (§197) over supported provider-supply dispatchers. Responses expose the source, observation, methodology, and confidence fields supplied by that dispatcher. The classifier output is runtime-validated against a strict whitelist enum and never produces SQL — typed dispatchers handle the data lookup." }, { "name": "Exports", "description": "LLM-ready exports (§198) for registered export dataset slugs. Supported payloads can include chunked text, structured fields, methodology, and citations in NDJSON, JSON, or text-block formats; consult the response for fields available to the selected dataset." }, { "name": "NpiEntityResolution", "description": "Cross-dataset entity resolution keyed by NPI. A response includes only the source blocks available for that identifier; source, date, and provenance fields vary by block and can be null." }, { "name": "Procurement", "description": "Federal-contractor screening over the loaded SAM.gov registration and exclusion, USASpending award, and FAPIIS records. Historical coordinates apply only to sources with retained versions; the current implementation banks USASpending award history. No risk score or derived verdict; re-confirm matches at the issuing authority." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (`fnt_`)", "description": "Pass the key shown once in your Fonteum account dashboard as `Authorization: Bearer fnt_...`. The live read-only sample is `fnt_DEMO_PUBLIC_V1`; create an account at https://fonteum.com/account/signup for an issued key." }, "DeveloperSession": { "type": "apiKey", "in": "cookie", "name": "__fnt_dev", "description": "HttpOnly developer-session cookie created by the Fonteum account login flow. Used only by browser/account endpoints; it is not an API key and cannot authenticate metered data requests." } }, "schemas": { "ProvenanceField": { "type": "object", "required": [ "value", "source", "last_checked" ], "properties": { "value": { "description": "The actual field value (any JSON type)." }, "source": { "type": "string", "example": "CMS NPPES NPI Registry" }, "source_url": { "type": "string", "format": "uri", "example": "https://npiregistry.cms.hhs.gov/api/" }, "last_checked": { "type": "string", "format": "date-time" }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "attribution_text": { "type": "string" }, "limitations": { "type": "string" } } }, "DataFreshness": { "type": "object", "required": [ "source", "last_refreshed" ], "properties": { "source": { "type": "string" }, "last_refreshed": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted." }, "source_release_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed." }, "artifact_snapshot_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp." }, "coverage_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Source-data coverage date or period boundary; not a publisher release or content-change timestamp." }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest workflow or source check, separate from content freshness." }, "last_observed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest source_snapshots ledger observation, separate from content freshness." }, "timestamp_basis": { "type": "string", "enum": [ "content_change" ], "nullable": true, "description": "Present only when last_refreshed is backed by a proved canonical content transition." }, "evidence_status": { "type": "string", "enum": [ "proved", "unavailable", "invalid", "conflicted", "error" ] }, "next_refresh_eta": { "type": "string", "format": "date-time", "nullable": true }, "cadence": { "type": "string" } } }, "OperationalState": { "type": "string", "enum": [ "operational", "degraded", "outage", "unknown" ], "description": "Canonical operational headline shared by health and status endpoints. It is derived from separately reported transport, pipeline, source-completeness, and incident dimensions." }, "OperationalStatus": { "type": "object", "description": "One dated operational assessment. Transport reachability, pipeline freshness, source completeness, and incidents remain separate so a data concern is not represented as a transport outage.", "required": [ "overall", "generated_at", "transport", "pipeline_freshness", "source_completeness", "incidents" ], "properties": { "overall": { "$ref": "#/components/schemas/OperationalState" }, "generated_at": { "type": "string", "format": "date-time" }, "transport": { "type": "object", "required": [ "state", "monitored_endpoint", "uptime_24h_pct", "uptime_30d_pct" ], "properties": { "state": { "$ref": "#/components/schemas/OperationalState" }, "monitored_endpoint": { "type": "string", "example": "/api/health" }, "uptime_24h_pct": { "type": "number", "nullable": true }, "uptime_30d_pct": { "type": "number", "nullable": true } } }, "pipeline_freshness": { "type": "object", "required": [ "state", "current_sources", "degraded_sources", "stale_sources", "legacy_unknown_sources", "legacy_failed_sources" ], "properties": { "state": { "type": "string", "enum": [ "current", "degraded", "unknown" ] }, "current_sources": { "type": "integer", "minimum": 0 }, "degraded_sources": { "type": "integer", "minimum": 0 }, "stale_sources": { "type": "integer", "minimum": 0 }, "legacy_unknown_sources": { "type": "integer", "minimum": 0 }, "legacy_failed_sources": { "type": "integer", "minimum": 0 } } }, "source_completeness": { "type": "object", "required": [ "state", "total_sources", "observed_sources", "unknown_sources", "quality_status", "quality_score" ], "properties": { "state": { "type": "string", "enum": [ "complete", "incomplete", "unknown" ] }, "total_sources": { "type": "integer", "minimum": 0 }, "observed_sources": { "type": "integer", "minimum": 0 }, "unknown_sources": { "type": "integer", "minimum": 0 }, "quality_status": { "type": "string", "enum": [ "current", "incomplete", "unavailable" ] }, "quality_score": { "type": "number", "nullable": true } } }, "incidents": { "type": "object", "required": [ "state", "open_count", "highest_severity", "schema_drift_sources", "quarantined_sources", "upstream_degraded_sources", "evidence_error_sources", "operations_status" ], "properties": { "state": { "type": "string", "enum": [ "clear", "active", "unknown" ] }, "open_count": { "type": "integer", "minimum": 0 }, "highest_severity": { "type": "string", "nullable": true, "enum": [ "critical", "error", "warning" ] }, "schema_drift_sources": { "type": "integer", "minimum": 0 }, "quarantined_sources": { "type": "integer", "minimum": 0 }, "upstream_degraded_sources": { "type": "integer", "minimum": 0 }, "evidence_error_sources": { "type": "integer", "minimum": 0 }, "operations_status": { "type": "string", "enum": [ "green", "red", "unobservable", "never-run", "unavailable" ] } } } } }, "PlatformCoverage": { "type": "object", "description": "Query-derived platform coverage from one public.platform_stats_snapshots row. The numeric coverage fields sources_integrated, sources_with_data, sources_fresh, and states_covered are as of as_of_date. Integrated, data-bearing, and fresh-observation counts are distinct. sources_complete is always null because the platform publishes no aggregate complete-source count. states_covered is a separate state Medicaid jurisdiction measure. The containing platform_coverage property is null when the read falls back or when any required query metric is absent.", "required": [ "as_of_date", "captured_at", "sources_integrated", "sources_with_data", "sources_fresh", "sources_complete", "states_covered", "definitions", "provenance" ], "properties": { "as_of_date": { "type": "string", "format": "date", "description": "Observation date that qualifies sources_integrated, sources_with_data, sources_fresh, and states_covered in this object." }, "captured_at": { "type": "string", "format": "date-time", "description": "When the platform-stats observation was captured; not an upstream source-refresh timestamp." }, "sources_integrated": { "type": "integer", "minimum": 0, "description": "As of the sibling as_of_date: active production source-registry rows. Integration does not imply a loaded or fresh source." }, "sources_with_data": { "type": "integer", "minimum": 0, "description": "As of the sibling as_of_date: distinct snapshot source IDs with at least one positive record count." }, "sources_fresh": { "type": "integer", "minimum": 0, "description": "As of the sibling as_of_date: distinct snapshot source IDs whose latest positive-data snapshot date is within the preceding 45 days. Recency does not prove a content change or serving state." }, "sources_complete": { "type": "integer", "nullable": true, "enum": [ null ], "description": "No platform-wide source-completeness count is published. Completeness is source-specific and must be evaluated against the named source's expected scope." }, "states_covered": { "type": "integer", "minimum": 0, "description": "As of the sibling as_of_date: distinct state values represented in the state Medicaid exclusions serving table." }, "definitions": { "type": "object", "required": [ "sources_integrated", "sources_with_data", "sources_fresh", "sources_complete", "states_covered" ], "properties": { "sources_integrated": { "type": "string" }, "sources_with_data": { "type": "string" }, "sources_fresh": { "type": "string" }, "sources_complete": { "type": "string" }, "states_covered": { "type": "string" } } }, "provenance": { "type": "object", "required": [ "source", "source_url", "dataset_id", "snapshot", "last_checked", "methodology", "limitations" ], "properties": { "source": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "dataset_id": { "type": "string" }, "snapshot": { "type": "string", "format": "date" }, "last_checked": { "type": "string", "format": "date-time" }, "methodology": { "type": "string" }, "limitations": { "type": "string" } } } } }, "AsOfSnapshotResponse": { "type": "object", "description": "Version 2 dataset-level as-of result. Public selection admits only source observations with a matching usable SHA-256 attestation. Selection windows identify which stored observation answers the requested date; they do not prove that upstream content changed or stayed unchanged between observations.", "required": [ "status", "source", "as_of", "record", "attestation", "coverage", "methodology_version" ], "properties": { "status": { "type": "string", "enum": [ "found", "before_tracking", "no_captures", "no_attested_captures" ], "description": "found selects an attested observation; before_tracking predates public attested coverage; no_captures means no stored observations exist; no_attested_captures means stored observations exist but none satisfy the public attestation boundary." }, "source": { "type": "object", "required": [ "source_id", "label", "authority", "official_url", "record_noun" ], "properties": { "source_id": { "type": "string" }, "label": { "type": "string" }, "authority": { "type": "string" }, "official_url": { "type": "string", "format": "uri" }, "record_noun": { "type": "string" } } }, "as_of": { "type": "string", "format": "date", "description": "Requested point in time normalized to a UTC date." }, "record": { "type": "object", "nullable": true, "description": "Selected observation and its half-open selection window; null unless status is found.", "required": [ "snapshot_id", "snapshot_date", "record_count", "source_release_date", "capture_methodology", "selection_from", "selection_to", "is_latest_attested_observation" ], "properties": { "snapshot_id": { "type": "integer", "minimum": 0 }, "snapshot_date": { "type": "string", "format": "date" }, "record_count": { "type": "integer", "minimum": 0, "nullable": true }, "source_release_date": { "type": "string", "format": "date", "nullable": true, "description": "Publisher release date when recorded; separate from the stored observation and selection dates." }, "capture_methodology": { "type": "string", "nullable": true }, "selection_from": { "type": "string", "format": "date", "description": "Inclusive start of the selected observation's public coverage window." }, "selection_to": { "type": "string", "format": "date", "nullable": true, "description": "Exclusive date of the next usable attested observation; null for the latest one." }, "is_latest_attested_observation": { "type": "boolean" } } }, "attestation": { "type": "object", "nullable": true, "description": "Stored re-check trail for the selected observation; null unless status is found. Null witness or chain fields mean a complete evidence read found no corresponding row, not that the read failed.", "required": [ "snapshot_id", "content_hash", "hash_algorithm", "attested_at", "witnessed", "witness_signature", "public_key_fingerprint", "chain_link_index", "chain_link_signature", "corrections", "verify_url", "verify_api_url", "chain_recheck_url", "key_url" ], "properties": { "snapshot_id": { "type": "integer", "minimum": 0 }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 value stored on the matching attestation row." }, "hash_algorithm": { "type": "string", "enum": [ "SHA-256" ] }, "attested_at": { "type": "string", "format": "date-time" }, "witnessed": { "type": "boolean" }, "witness_signature": { "type": "string", "nullable": true }, "public_key_fingerprint": { "type": "string", "nullable": true }, "chain_link_index": { "type": "integer", "minimum": 0, "nullable": true }, "chain_link_signature": { "type": "string", "nullable": true }, "corrections": { "type": "array", "items": { "type": "object", "required": [ "correction_id", "wrong_value", "corrected_value", "reason", "issued_at" ], "properties": { "correction_id": { "type": "string" }, "wrong_value": { "type": "string" }, "corrected_value": { "type": "string" }, "reason": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" } } } }, "verify_url": { "type": "string", "format": "uri" }, "verify_api_url": { "type": "string", "format": "uri" }, "chain_recheck_url": { "type": "string", "format": "uri" }, "key_url": { "type": "string", "format": "uri" } } }, "coverage": { "type": "object", "description": "Coverage over usable attested observations only; staged observations without matching attestations are excluded.", "required": [ "first_captured", "last_captured", "capture_count" ], "properties": { "first_captured": { "type": "string", "format": "date", "nullable": true }, "last_captured": { "type": "string", "format": "date", "nullable": true }, "capture_count": { "type": "integer", "minimum": 0 } } }, "methodology_version": { "type": "string", "enum": [ "as-of-snapshot/v2" ] } } }, "AsOfSnapshotError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_date", "unknown_source", "as_of_query_failed" ] }, "message": { "type": "string" } } } } }, "ExclusionCoverage": { "type": "object", "required": [ "status", "sources", "message" ], "properties": { "status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "serving_as_of": { "type": "string", "format": "date", "nullable": true }, "attested_as_of": { "type": "string", "format": "date", "nullable": true }, "attestation_snapshot_id": { "type": "integer", "nullable": true }, "evidence_kind": { "type": "string", "enum": [ "attested_artifact", "serving_table_observation", "none" ] }, "reason": { "type": "string" } } } }, "message": { "type": "string" } } }, "ExclusionScreenData": { "type": "object", "required": [ "npi", "checked_at", "excluded", "compromised_anywhere", "coverage", "coverage_status", "determination" ], "properties": { "npi": { "type": "string", "pattern": "^\\d{10}$" }, "checked_at": { "type": "string", "format": "date-time" }, "authenticated": { "type": "boolean" }, "excluded": { "type": "boolean", "nullable": true, "description": "Null when coverage is stale or indeterminate; never false unless coverage is current." }, "excluded_by": { "type": "array", "items": { "type": "string" } }, "record_count": { "type": "integer" }, "exclusions": { "type": "array", "items": { "type": "object" } }, "compromised_anywhere": { "type": "boolean", "nullable": true, "description": "Null for a zero-match screen when exclusion coverage is stale or indeterminate." }, "flagged": { "type": "boolean" }, "flagged_by": { "type": "array", "items": { "type": "string" } }, "flag_count": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object" } }, "sources": { "type": "object", "additionalProperties": { "type": "object" } }, "coverage": { "$ref": "#/components/schemas/ExclusionCoverage" }, "coverage_status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "determination": { "type": "string", "enum": [ "match", "no_match", "indeterminate" ] }, "disclaimer": { "type": "string" } } }, "TrustMark": { "type": "object", "description": "Re-checkable attribution attached to v1 response metadata. The chain-head value is a 32-byte content hash, not an Ed25519 signature. Per-snapshot witness signatures use a separately scoped evidence object and never occupy this contract.", "required": [ "attested_by", "standard", "content_credential", "source", "as_of", "attestation_id", "chain_head_hash", "recheck_url", "key_url", "docs_url" ], "properties": { "attested_by": { "type": "string", "enum": [ "Fonteum" ] }, "standard": { "type": "string", "enum": [ "W3C-VC-2.0" ] }, "content_credential": { "type": "string", "enum": [ "C2PA-aligned Content Credentials for facts" ] }, "source": { "type": "string", "nullable": true }, "as_of": { "type": "string", "nullable": true }, "attestation_id": { "type": "integer", "nullable": true, "description": "Snapshot id when a specific snapshot is in scope; otherwise the live chain-head link index." }, "chain_head_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true, "description": "Current chain-head content hash. This field is deliberately not named or represented as a signature." }, "recheck_url": { "type": "string", "format": "uri" }, "key_url": { "type": "string", "format": "uri", "description": "Signing-key directory used by separately exposed chain and witness evidence." }, "docs_url": { "type": "string", "format": "uri" } } }, "ChainAnchorSummary": { "type": "object", "required": [ "anchor_type", "target_ref", "digest_hex", "digest_short", "calendar_url", "status", "state", "proof_generation", "bitcoin_block_height", "provider", "block_id", "submitted_at", "verified_at", "quarantine_reason" ], "properties": { "anchor_type": { "type": "string", "enum": [ "daily_merkle_root", "attestation_hash", "chain_head", "digest" ] }, "target_ref": { "type": "string", "nullable": true }, "digest_hex": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "digest_short": { "type": "string" }, "calendar_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "quarantined", "pending", "mainnet_verified" ] }, "state": { "type": "string", "enum": [ "quarantined", "pending", "mainnet_verified" ] }, "proof_generation": { "type": "integer", "nullable": true, "minimum": 1 }, "bitcoin_block_height": { "type": "integer", "nullable": true, "minimum": 0 }, "provider": { "type": "string", "nullable": true }, "block_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "quarantine_reason": { "type": "string", "nullable": true } } }, "ChainAnchorsResponse": { "type": "object", "required": [ "active", "table_present", "attempts_table_present", "counts", "chain", "chain_head_anchor", "latest_mainnet_verified", "latest_submission_at", "note", "evidence_policy", "chain_url", "status_url", "docs_url" ], "properties": { "active": { "type": "boolean", "description": "True only when the chain is fresh and a pending or mainnet_verified attempt targets the exact current head." }, "table_present": { "type": "boolean" }, "attempts_table_present": { "type": "boolean" }, "counts": { "type": "object", "required": [ "total", "quarantined", "pending", "mainnet_verified" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "quarantined": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "mainnet_verified": { "type": "integer", "minimum": 0 } } }, "chain": { "type": "object", "required": [ "fresh", "last_extended_at", "age_seconds", "stale_after_seconds" ], "properties": { "fresh": { "type": "boolean" }, "last_extended_at": { "type": "string", "format": "date-time", "nullable": true }, "age_seconds": { "type": "number", "minimum": 0, "nullable": true }, "stale_after_seconds": { "type": "integer", "minimum": 1 } } }, "chain_head_anchor": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ChainAnchorSummary" } ], "nullable": true }, "latest_mainnet_verified": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ChainAnchorSummary" } ], "nullable": true }, "latest_submission_at": { "type": "string", "format": "date-time", "nullable": true }, "note": { "type": "string" }, "evidence_policy": { "type": "string" }, "chain_url": { "type": "string", "format": "uri" }, "status_url": { "type": "string", "format": "uri" }, "docs_url": { "type": "string", "format": "uri" } } }, "SignedTreeHead": { "type": "object", "required": [ "tree_size", "root_hash", "signature", "key_id", "signed_at" ], "properties": { "tree_size": { "type": "integer", "minimum": 0 }, "root_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "nullable": true }, "signature": { "type": "string", "nullable": true }, "key_id": { "type": "string", "nullable": true }, "signed_at": { "type": "string", "format": "date-time" } } }, "TransparencyHeadResponse": { "type": "object", "required": [ "schema", "algorithm", "merkle", "leaf_count", "signed_tree_head", "inclusion_proof_url", "key_directory_url", "external_anchors", "docs_url" ], "properties": { "schema": { "type": "string", "enum": [ "fonteum-signature-transparency-log/v1" ] }, "algorithm": { "type": "string", "enum": [ "Ed25519" ] }, "merkle": { "type": "string" }, "leaf_count": { "type": "integer", "minimum": 0 }, "signed_tree_head": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SignedTreeHead" } ], "nullable": true }, "inclusion_proof_url": { "type": "string", "format": "uri-template" }, "key_directory_url": { "type": "string", "format": "uri" }, "external_anchors": { "type": "object", "required": [ "status_url", "claim_policy" ], "properties": { "status_url": { "type": "string", "format": "uri" }, "claim_policy": { "type": "string" } } }, "docs_url": { "type": "string", "format": "uri" } } }, "ResponseMeta": { "type": "object", "required": [ "request_id", "api_version", "data_freshness", "methodology_url", "limitations_url", "attestation" ], "properties": { "request_id": { "type": "string", "example": "req_abc123def456" }, "api_version": { "type": "string", "enum": [ "v1" ] }, "data_freshness": { "description": "One source block or an array of source blocks. Fields keep content-change, publisher-release, artifact-snapshot, coverage, check, and observation timestamps separate; only a proved canonical content transition can make last_refreshed non-null.", "oneOf": [ { "$ref": "#/components/schemas/DataFreshness" }, { "type": "array", "items": { "$ref": "#/components/schemas/DataFreshness" } } ] }, "methodology_url": { "type": "string", "format": "uri" }, "limitations_url": { "type": "string", "format": "uri" }, "documentation_url": { "type": "string", "format": "uri" }, "geo_scope_note": { "type": "string" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "freshness": { "type": "array", "description": "Typed per-source stored-observation timing: snapshot date, configured target, and a computed age state. This measures the stored observation against Fonteum's configured target, not upstream publisher freshness. A `current` state requires a dated stored snapshot; an unconfirmable date renders `unknown`.", "items": { "$ref": "#/components/schemas/FreshnessBlock" } }, "freshness_policy": { "$ref": "#/components/schemas/FreshnessPolicy" }, "attestation": { "$ref": "#/components/schemas/TrustMark" } } }, "FreshnessBlock": { "type": "object", "required": [ "source_id", "snapshot", "last_checked", "state" ], "properties": { "source_id": { "type": "string", "example": "oig-leie" }, "snapshot": { "type": "string", "format": "date", "nullable": true, "description": "Source publication date; null when unavailable (state then `unknown`)." }, "last_checked": { "type": "string", "format": "date-time", "description": "Serve-time — the only `now` field." }, "sla_days": { "type": "integer", "nullable": true }, "sla_hours": { "type": "integer", "nullable": true }, "age_hours": { "type": "integer", "nullable": true }, "age_days": { "type": "integer", "nullable": true }, "within_sla": { "type": "boolean", "nullable": true }, "state": { "type": "string", "enum": [ "current", "degraded", "stale", "unknown" ] } } }, "FreshnessPolicy": { "type": "object", "description": "Present only when the request set `max_staleness`. Reports whether each consulted stored source observation met the caller's age bar; it does not assert that the upstream publisher released newer data.", "required": [ "requested", "max_staleness", "max_staleness_hours", "mode", "stale", "stale_sources" ], "properties": { "requested": { "type": "boolean", "enum": [ true ] }, "max_staleness": { "type": "string", "example": "48h" }, "max_staleness_hours": { "type": "number", "example": 48 }, "mode": { "type": "string", "enum": [ "flag", "reject" ] }, "stale": { "type": "boolean" }, "stale_sources": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string" }, "state": { "type": "string", "enum": [ "current", "degraded", "stale", "unknown" ] }, "age_hours": { "type": "integer", "nullable": true }, "reason": { "type": "string", "enum": [ "exceeds_max_staleness", "freshness_unknown" ] } } } } } }, "ApiError": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "rate_limit_exceeded" }, "message": { "type": "string" }, "details": {} } }, "meta": { "type": "object", "required": [ "request_id", "api_version" ], "properties": { "request_id": { "type": "string" }, "api_version": { "type": "string", "enum": [ "v1" ] } } } } }, "SpecialtyListItem": { "type": "object", "properties": { "slug": { "type": "string", "example": "dermatology" }, "display_name": { "type": "string", "example": "Dermatology" }, "taxonomy_codes": { "type": "array", "items": { "type": "string" }, "example": [ "207N00000X" ] }, "study_url": { "type": "string", "format": "uri", "example": "https://fonteum.com/research" }, "release_date": { "type": "string", "format": "date" } } }, "SpecialtyStateRow": { "type": "object", "properties": { "state_code": { "$ref": "#/components/schemas/ProvenanceField" }, "state_name": { "$ref": "#/components/schemas/ProvenanceField" }, "active_providers": { "$ref": "#/components/schemas/ProvenanceField" }, "population_2024": { "$ref": "#/components/schemas/ProvenanceField" }, "per_100k": { "$ref": "#/components/schemas/ProvenanceField" }, "rank_density": { "$ref": "#/components/schemas/ProvenanceField" }, "quartile": { "$ref": "#/components/schemas/ProvenanceField" }, "underserved": { "$ref": "#/components/schemas/ProvenanceField" } } }, "QppMipsScore": { "type": "object", "description": "CMS QPP MIPS scores for one performance year. Scores can be null when CMS did not publish that category for the row.", "required": [ "performance_year", "final_score", "category_scores", "participation_type" ], "properties": { "performance_year": { "type": "integer", "minimum": 2017 }, "final_score": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "category_scores": { "type": "object", "required": [ "quality", "cost", "improvement_activities", "promoting_interoperability" ], "properties": { "quality": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "cost": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "improvement_activities": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true }, "promoting_interoperability": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true } } }, "participation_type": { "type": "string", "nullable": true } } }, "ProviderRecord": { "type": "object", "properties": { "npi": { "$ref": "#/components/schemas/ProvenanceField" }, "specialty": { "$ref": "#/components/schemas/ProvenanceField" }, "taxonomy_codes": { "$ref": "#/components/schemas/ProvenanceField" }, "taxonomy_primary": { "$ref": "#/components/schemas/ProvenanceField" }, "state": { "$ref": "#/components/schemas/ProvenanceField" }, "city": { "$ref": "#/components/schemas/ProvenanceField" }, "last_updated_in_source": { "$ref": "#/components/schemas/ProvenanceField" } } } }, "parameters": { "MaxStaleness": { "name": "max_staleness", "in": "query", "required": false, "description": "Caller stored-snapshot age bar (moat-defense #125). A positive duration — `48h`, `7d`, `90m`, or a bare number of hours. The maximum age any consulted stored source snapshot may have for this request; it is not an upstream-release freshness guarantee. Response carries `meta.freshness_policy`; absence of the parameter leaves default behaviour unchanged.", "schema": { "type": "string", "example": "48h" } }, "MaxStalenessMode": { "name": "max_staleness_mode", "in": "query", "required": false, "description": "What to do when a source is behind the `max_staleness` bar: `flag` (default) returns 200 with a stale flag; `reject` returns 409. `on_stale=reject|409` is accepted as an alias.", "schema": { "type": "string", "enum": [ "flag", "reject" ], "default": "flag" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "StaleRejected": { "description": "A consulted stored source observation is behind the caller's `max_staleness` bar and `max_staleness_mode=reject` was set. The body still carries `data` + `meta.freshness_policy` (which observations failed and why); the read is not presented as meeting the configured age bar.", "content": { "application/json": { "schema": { "type": "object" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer", "format": "int64" }, "description": "Unix epoch second for the effective reset." }, "X-RateLimit-Reset-At": { "schema": { "type": "string", "format": "date-time" }, "description": "The effective reset as an ISO timestamp." }, "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "RateLimitUnavailable": { "description": "Rate-limit storage is temporarily unavailable.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiError" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit_unavailable" ] }, "message": { "type": "string", "enum": [ "Rate-limit service is temporarily unavailable." ] } } } } } ] } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Canonical operational state + available source timing", "description": "Public endpoint. HTTP 200 is the transport-liveness response sampled by the uptime monitor. Its body carries the shared canonical operational headline plus separate transport, pipeline-freshness, source-completeness, and incident dimensions; the compatibility source list does not independently classify service health.", "security": [], "responses": { "200": { "description": "Health report. HTTP 200 means the liveness route responded; data concerns appear in the canonical body state and never change that transport response code.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "status", "operational_state", "uptime_target", "sources", "api_version" ], "properties": { "status": { "$ref": "#/components/schemas/OperationalState" }, "operational_state": { "$ref": "#/components/schemas/OperationalStatus" }, "uptime_target": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object" } }, "api_version": { "type": "string", "enum": [ "v1" ] } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } }, "/as-of/{source_id}": { "get": { "tags": [ "Integrity" ], "operationId": "getSourceSnapshotAsOf", "summary": "Select an attested source observation as of a date", "description": "Public dataset-grain point-in-time read using methodology as-of-snapshot/v2. Only source observations with a matching usable SHA-256 attestation are selectable. The returned half-open selection window identifies which stored observation answers the requested date; it does not prove that the upstream source changed or remained unchanged between observations. Evidence-storage failures return 500 instead of a partial record.", "security": [], "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "oig_leie", "nppes", "pecos_ppef", "cms_pos_facilities", "cms_care_compare_nh", "cms_qpp_mips_individual", "cms_open_payments", "cms_care_compare_dialysis", "cms_care_compare_hospice", "cms_civil_money_penalties" ] }, "description": "Curated source_snapshots namespace exposed by GET /api/v1/as-of discovery." }, { "name": "date", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "description": "ISO date or timestamp for the point-in-time selection. Defaults to the current time; the legacy `at` query alias is also accepted." } ], "responses": { "200": { "description": "Attested as-of result. Coverage states such as no_attested_captures are successful reads and remain HTTP 200.", "headers": { "X-Fonteum-Methodology-Version": { "description": "Pinned response methodology identifier: as-of-snapshot/v2.", "schema": { "type": "string", "enum": [ "as-of-snapshot/v2" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsOfSnapshotResponse" } } } }, "400": { "description": "date/at is not a valid ISO date or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsOfSnapshotError" } } } }, "404": { "description": "source_id is not in the curated public as-of source allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsOfSnapshotError" } } } }, "500": { "description": "Capture, attestation, witness, or chain evidence could not be read completely; no partial result is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsOfSnapshotError" } } } } } } }, "/status": { "get": { "tags": [ "Health" ], "summary": "Canonical operational state + source findings", "description": "Public endpoint (moat-defense #125). `data.summary.overall` and `data.operational_state.overall` are the shared canonical operational state. Its four dimensions separate transport uptime, pipeline freshness, source completeness, and incidents. `summary.findings_state` is a narrower source-report finding for the records represented here; it is not a second service headline. Per-source fields do not establish upstream freshness for omitted sources, and partial ledger reads remain explicit in availability flags.", "security": [], "responses": { "200": { "description": "Source-status report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "availability", "summary", "sources", "operational_state" ], "properties": { "availability": { "type": "object", "required": [ "registry", "snapshots", "crosswalk", "drift", "quarantine", "health" ], "properties": { "registry": { "type": "boolean" }, "snapshots": { "type": "boolean" }, "crosswalk": { "type": "boolean", "description": "Whether the durable registry-to-snapshot source-key crosswalk was readable for this report." }, "drift": { "type": "boolean" }, "quarantine": { "type": "boolean" }, "health": { "type": "boolean" } } }, "summary": { "type": "object", "required": [ "overall", "findings_state" ], "properties": { "overall": { "$ref": "#/components/schemas/OperationalState" }, "findings_state": { "type": "string", "enum": [ "ok", "attention" ] }, "total_sources": { "type": "integer" }, "current": { "type": "integer" }, "degraded": { "type": "integer" }, "stale": { "type": "integer" }, "unknown": { "type": "integer" }, "sources_with_open_drift": { "type": "integer" }, "sources_quarantined": { "type": "integer" }, "sources_degraded_upstream": { "type": "integer" }, "sources_with_evidence_error": { "type": "integer" } } }, "operational_state": { "$ref": "#/components/schemas/OperationalStatus" }, "sources": { "type": "array", "items": { "type": "object" } } } }, "provenance": { "type": "object" }, "meta": { "type": "object" } } } } } } } } }, "/chain/manifest": { "get": { "tags": [ "Integrity" ], "summary": "Download the complete chain-link manifest", "description": "Public, no-store manifest of the actual chain_links sequence and each referenced snapshot attestation. Unattached attestation rows are not chain members and are not exported. Reads are fully paginated and joined to source_snapshots for row_count; incomplete evidence fails closed with 503.", "security": [], "responses": { "200": { "description": "Complete chain-link manifest in ascending link_index order, including genesis.", "content": { "application/json": { "schema": { "type": "object", "required": [ "bootstrapped", "complete", "public_key", "public_key_id", "public_key_url", "chain_url", "verify_url", "total_links", "head_link_index", "head_link_hash", "latest_hash", "latest_snapshot", "returned", "snapshots", "returned_links", "links" ], "properties": { "bootstrapped": { "type": "boolean", "description": "True only when the chain has a public key, key id, and at least one link." }, "complete": { "type": "boolean", "enum": [ true ], "description": "Always true on HTTP 200; incomplete reads fail closed with HTTP 503." }, "public_key": { "type": "string", "nullable": true }, "public_key_id": { "type": "string", "nullable": true }, "public_key_url": { "type": "string", "format": "uri" }, "chain_url": { "type": "string", "format": "uri" }, "verify_url": { "type": "string", "format": "uri" }, "total_links": { "type": "integer", "nullable": true, "minimum": 0 }, "latest_hash": { "type": "string", "nullable": true, "pattern": "^[0-9a-f]{64}$", "deprecated": true, "description": "Compatibility alias of head_link_hash; this is a chain-link hash, not a snapshot digest." }, "head_link_index": { "type": "integer", "nullable": true, "minimum": 0 }, "head_link_hash": { "type": "string", "nullable": true, "pattern": "^[0-9a-f]{64}$" }, "latest_snapshot": { "type": "object", "nullable": true, "deprecated": true, "description": "Compatibility summary of the attestation referenced by the head chain link. It never substitutes an unattached newer attestation.", "required": [ "timestamp", "dataset", "rows", "content_hash", "hash_version", "chain_link_index" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "dataset": { "type": "string" }, "rows": { "type": "integer", "minimum": 0 }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hash_version": { "type": "string" }, "chain_link_index": { "type": "integer", "minimum": 0 } } }, "returned": { "type": "integer", "minimum": 0, "deprecated": true, "description": "Compatibility count for snapshots: linked attestations only, excluding genesis." }, "snapshots": { "type": "array", "deprecated": true, "description": "Newest-first compatibility projection of linked snapshot attestations. Unattached attestations are excluded.", "items": { "type": "object", "required": [ "attestation_id", "snapshot_id", "source_id", "snapshot_date", "content_hash", "digest", "hash_algorithm", "hash_version", "row_count", "signed_at", "chain_link_index", "chain_link_hash", "content_size_bytes", "legacy_content_size_field_value", "content_size_limitation" ], "properties": { "attestation_id": { "type": "integer", "minimum": 0 }, "snapshot_id": { "type": "integer", "minimum": 0 }, "source_id": { "type": "string" }, "snapshot_date": { "type": "string", "format": "date" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hash_algorithm": { "type": "string", "enum": [ "SHA-256" ] }, "hash_version": { "type": "string" }, "row_count": { "type": "integer", "minimum": 0 }, "signed_at": { "type": "string", "format": "date-time" }, "chain_link_index": { "type": "integer", "minimum": 0 }, "chain_link_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "content_size_bytes": { "type": "integer", "nullable": true, "minimum": 0 }, "legacy_content_size_field_value": { "type": "integer", "nullable": true, "minimum": 0 }, "content_size_limitation": { "type": "string", "nullable": true } } } }, "returned_links": { "type": "integer", "minimum": 0 }, "links": { "type": "array", "items": { "type": "object", "required": [ "link_index", "prev_hash", "attestation_id", "attestation_content_hash", "content_hash", "signature", "public_key_id", "signed_at", "created_at", "attestation" ], "properties": { "link_index": { "type": "integer", "minimum": 0 }, "prev_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "attestation_id": { "type": "integer", "nullable": true, "minimum": 0 }, "attestation_content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "signature": { "type": "string", "pattern": "^[0-9a-f]{128}$" }, "public_key_id": { "type": "string" }, "signed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "attestation": { "type": "object", "nullable": true, "description": "Null for the genesis link only.", "required": [ "attestation_id", "snapshot_id", "source_id", "snapshot_date", "content_hash", "hash_algorithm", "hash_version", "row_count", "content_size_bytes", "legacy_content_size_field_value", "content_size_limitation", "attested_at" ], "properties": { "attestation_id": { "type": "integer", "minimum": 0 }, "snapshot_id": { "type": "integer", "minimum": 0 }, "source_id": { "type": "string" }, "snapshot_date": { "type": "string", "format": "date" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "hash_algorithm": { "type": "string", "enum": [ "SHA-256" ] }, "hash_version": { "type": "string" }, "row_count": { "type": "integer", "minimum": 0 }, "content_size_bytes": { "type": "integer", "nullable": true, "minimum": 0 }, "legacy_content_size_field_value": { "type": "integer", "nullable": true, "minimum": 0 }, "content_size_limitation": { "type": "string", "nullable": true, "description": "Disclosure for count-observation-v1 entries whose legacy size field contained a row count rather than bytes." }, "attested_at": { "type": "string", "format": "date-time" } } } } } }, "_note": { "type": "string", "description": "Present when the append-only chain has not yet been bootstrapped." } } } } } }, "503": { "description": "Integrity storage read or source-snapshot join failed; no partial manifest is returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "detail", "_note" ], "properties": { "error": { "type": "string", "enum": [ "integrity_manifest_unavailable" ] }, "detail": { "type": "string" }, "_note": { "type": "string" } } } } } } } } }, "/chain/verify": { "get": { "tags": [ "Integrity" ], "summary": "Re-check a stored immutable chain link", "description": "Public endpoint. Recomputes one stored link's content hash, resolves its exact signing-key id, checks the Ed25519 signature, and checks prev_hash against the preceding stored link. With no link_index it checks the current head. Storage failures return 503 rather than being misreported as cryptographic failures.", "security": [], "parameters": [ { "name": "link_index", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based chain link index. Omit to re-check the current head." } ], "responses": { "200": { "description": "Cryptographic result. A failed check is valid=false with an errors array.", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "link": { "type": "object", "nullable": true } } } } } }, "400": { "description": "Malformed link_index." }, "503": { "description": "Chain or signing-key storage unavailable." } } }, "post": { "tags": [ "Integrity" ], "summary": "Re-check an API-shaped chain link", "description": "Public endpoint. Accepts a chain-link object and runs the same content-hash, exact-key Ed25519, and prev_hash checks as GET. UTC timestamps serialized with Z or +00:00 canonicalize to the same signed preimage.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link_index", "prev_hash", "attestation_id", "attestation_content_hash", "content_hash", "signature", "public_key_id", "signed_at" ], "properties": { "link_index": { "type": "integer", "minimum": 0 }, "prev_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "attestation_id": { "type": "integer", "nullable": true, "minimum": 0 }, "attestation_content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "signature": { "type": "string", "pattern": "^[0-9a-f]{128}$" }, "public_key_id": { "type": "string" }, "signed_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Cryptographic result. A failed check is valid=false with an errors array.", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "errors" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Malformed JSON or link object." }, "503": { "description": "Chain or signing-key storage unavailable." } } } }, "/chain/anchors": { "get": { "tags": [ "Integrity" ], "summary": "Inspect external timestamp evidence", "description": "Public, no-store endpoint for append-only timestamp attempts. Legacy proofs are quarantined. A result reaches mainnet_verified only with a retained proof path and Bitcoin Core active-chain header evidence. active is true only when a pending or mainnet_verified attempt targets the exact current chain head and the chain has advanced within six hours; pending denotes operational activity, not Bitcoin confirmation.", "security": [], "responses": { "200": { "description": "Timestamp-attempt status, evidence counts, and current chain liveness.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainAnchorsResponse" }, "example": { "active": false, "table_present": true, "attempts_table_present": true, "counts": { "total": 162, "quarantined": 162, "pending": 0, "mainnet_verified": 0 }, "chain": { "fresh": true, "last_extended_at": "2026-07-12T12:00:00.000Z", "age_seconds": 300, "stale_after_seconds": 21600 }, "chain_head_anchor": null, "latest_mainnet_verified": null, "latest_submission_at": null, "note": "Legacy proofs are quarantined.", "evidence_policy": "Block heights appear only with retained Bitcoin Core active-chain evidence.", "chain_url": "https://fonteum.com/api/v1/chain", "status_url": "https://fonteum.com/chain/status", "docs_url": "https://fonteum.com/docs/chain" } } } } } } }, "/transparency": { "get": { "tags": [ "Integrity" ], "summary": "Read the signed transparency-log head", "description": "Public, no-store read of the RFC 6962 signature-log head and its Ed25519 signature. The log remains independently re-checkable without an external mainnet timestamp. Legacy proofs are quarantined, and this response makes no Bitcoin claim from a calendar receipt or stored block height.", "security": [], "responses": { "200": { "description": "Current signature-log size, signed tree head, and evidence-aware external-anchor pointer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransparencyHeadResponse" } } } } } } }, "/exclusions/{npi}": { "get": { "tags": [ "Providers" ], "summary": "Screen one NPI across federal and state exclusion lists", "description": "Returns exclusion and compromised-flag matches with available per-source provenance and serving-vs-attested coverage evidence. A zero-match result is returned only when the endpoint's internal coverage guard reports `current` after reconciliation; that state does not assert same-day upstream freshness. If a zero-match screen trails or cannot reconcile to its latest comparable internal artifact, the endpoint returns HTTP 503 with `determination: indeterminate`, nullable exclusion booleans, and `Cache-Control: no-store`. Positive matches remain HTTP 200 and disclose the noncurrent coverage status. An indeterminate response is not a clearance.", "parameters": [ { "name": "npi", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" } } ], "responses": { "200": { "description": "Match, or no-match when the endpoint's internal coverage guard reports reconciled `current` coverage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExclusionScreenData" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "NPI is not exactly 10 digits." }, "429": { "description": "Rate limit exceeded." }, "503": { "description": "Coverage stale or indeterminate. The body includes the nullable screening data and exact coverage evidence; no negative determination was made.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "data": { "$ref": "#/components/schemas/ExclusionScreenData" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } }, "/qpp-mips/{npi}": { "get": { "operationId": "getQppMipsScores", "tags": [ "Providers" ], "summary": "Read CMS QPP MIPS scores for one NPI", "description": "Returns the CMS-published MIPS final score, four category scores, and participation type for each loaded performance year, newest first. The production table has no populated payment-adjustment percentage field, so this contract does not advertise or emit one. `found=false` means no row is present in the data Fonteum currently holds; it does not establish that the clinician did not participate. Re-confirm consequential use at qpp.cms.gov.", "parameters": [ { "name": "npi", "in": "path", "required": true, "description": "Exact 10-digit National Provider Identifier.", "schema": { "type": "string", "pattern": "^\\d{10}$" } }, { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "responses": { "200": { "description": "Loaded QPP MIPS history for the NPI, or found=false when no row is present.", "headers": { "X-Fonteum-Methodology-Version": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "provenance", "disclaimer", "meta" ], "properties": { "data": { "type": "object", "required": [ "npi", "found", "latest", "history" ], "properties": { "npi": { "type": "string", "pattern": "^\\d{10}$" }, "found": { "type": "boolean" }, "latest": { "allOf": [ { "$ref": "#/components/schemas/QppMipsScore" } ], "nullable": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/QppMipsScore" } } } }, "provenance": { "type": "object", "description": "CMS QPP source, source URL, performance-year snapshot, methodology, license, coverage period, and serve-time fields available from the shared provenance builder." }, "disclaimer": { "type": "string" }, "meta": { "type": "object", "required": [ "api_version", "freshness", "methodology_url", "documentation_url" ], "properties": { "api_version": { "type": "string", "enum": [ "v1" ] }, "freshness": { "type": "array", "items": { "$ref": "#/components/schemas/FreshnessBlock" } }, "freshness_policy": { "$ref": "#/components/schemas/FreshnessPolicy" }, "methodology_url": { "type": "string", "format": "uri" }, "documentation_url": { "type": "string", "format": "uri" } } } } } } } }, "400": { "description": "NPI is not exactly 10 digits, or max_staleness is malformed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "CMS QPP MIPS lookup failed." }, "503": { "$ref": "#/components/responses/RateLimitUnavailable" } } } }, "/openapi.json": { "get": { "tags": [ "Health" ], "summary": "OpenAPI 3.0 spec", "description": "Public. Returns this document.", "security": [], "responses": { "200": { "description": "OpenAPI spec.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/billing/checkout": { "get": { "tags": [ "Billing" ], "summary": "Describe the browser Checkout contract", "description": "Public discovery response for the account-bound hosted Checkout endpoint. GET creates no Stripe object and moves no money.", "security": [], "responses": { "200": { "description": "Checkout endpoint contract.", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Start an account-bound Stripe Checkout Session", "description": "Browser endpoint. Requires an active Fonteum developer-session cookie, resolves the signed-in developer account's Stripe Customer, and creates a hosted Checkout Session bound with `client_reference_id` and account/plan metadata. The returned Stripe URL ultimately redirects to `/checkout/success?session_id={CHECKOUT_SESSION_ID}`. Self-serve products are paid Line-B API tiers and the one-time $129 signed certificate; recurring Line-A monitoring is not published or accepted until its fulfillment exists. This endpoint is not authenticated by the Bearer API key.", "security": [ { "DeveloperSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "planId", "interval" ], "additionalProperties": false, "properties": { "planId": { "type": "string", "enum": [ "a-certificate", "b-builder", "b-scale", "b-business" ] }, "interval": { "type": "string", "enum": [ "month", "year", "once" ] } } } } } }, "responses": { "200": { "description": "Hosted Stripe Checkout URL. Response is `no-store`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid JSON, plan, interval, or non-self-serve selection.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No active developer account session.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "The account already has a subscription or another subscription Checkout reservation is in progress.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Checkout burst limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Checkout is disabled until both Stripe secrets exist; certificate Checkout also requires the established signing key.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/procurement/screen": { "get": { "tags": [ "Procurement" ], "summary": "Screen a federal contractor by UEI or CAGE", "description": "Screen one US federal entity against the currently loaded SAM.gov registration and exclusion data, USASpending award data, and available FAPIIS and FAR 4.18 fields. Returned blocks identify available source and date metadata and include a 'confirm at SAM.gov' pointer; provenance fields can be null.\n\nProvide exactly one of `uei` or `cage`. Pass `as_of=YYYY-MM-DD` to query retained SAM or procurement history where rows have been banked; this is not universal replay for every entity or date. A zero-exclusion or unknown-identifier result is returned only when SAM serving coverage reconciles to a comparable attested artifact; otherwise HTTP 503 carries `exclusion_determination: indeterminate` and the coverage evidence.\n\nDefamation-safe: no risk score, no 'fraudulent' / 'likely excluded' label, no derived verdict; confirmed UEI/CAGE matches only; opt-out entities withheld; public-tier federal data only (no FOUO). Screening aid, not a certification.\n\nRequires `Authorization: Bearer fnt_...` and uses the key's configured limits.", "parameters": [ { "name": "uei", "in": "query", "required": false, "description": "12-char GSA Unique Entity ID (the procurement spine). Provide this OR `cage`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{12}$" } }, { "name": "cage", "in": "query", "required": false, "description": "5-char CAGE/NCAGE code; resolved to the entity's UEI. Provide this OR `uei`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{5}$" } }, { "name": "as_of", "in": "query", "required": false, "description": "ISO date (YYYY-MM-DD). The retained coordinate currently applies only to banked USASpending award rows; SAM.gov registration, exclusions, FAPIIS, and ownership fields may be current, absent, or null. Omit for the current request.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Screening result with dated facts and available per-source provenance. A zero-active-exclusion, unknown-identifier, or opted-out result is HTTP 200 only when the endpoint's SAM coverage guard reports internally reconciled `current`; otherwise the fail-closed response is HTTP 503.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "query": { "type": "object" }, "mode": { "type": "string", "enum": [ "current", "as_of_history" ] }, "screened": { "type": "boolean" }, "record_found": { "type": "boolean" }, "entity_coverage": { "type": "string", "enum": [ "ingested", "not_ingested" ] }, "registration": { "type": "object", "nullable": true }, "exclusions": { "type": "array", "items": { "type": "object" } }, "exclusion_summary": { "type": "object" }, "exclusion_coverage": { "$ref": "#/components/schemas/ExclusionCoverage" }, "exclusion_coverage_status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "exclusion_determination": { "type": "string", "enum": [ "match", "no_match", "indeterminate" ] }, "awards": { "type": "object" }, "fapiis": { "type": "array", "items": { "type": "object" } }, "ownership": { "type": "array", "items": { "type": "object" } }, "provenance": { "type": "object" }, "data_as_of": { "type": "string" }, "confirm_at": { "type": "string" }, "disclaimer": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Malformed request — missing/both identifiers, bad UEI/CAGE, or bad as_of." }, "429": { "description": "Rate limit exceeded." }, "503": { "description": "SAM exclusion coverage is stale or cannot be reconciled to an attested source artifact. No negative exclusion determination was made." } } } }, "/specialties": { "get": { "tags": [ "Specialties" ], "summary": "List all available specialties", "parameters": [ { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "responses": { "200": { "description": "Specialty list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecialtyListItem" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Bad request — `invalid_max_staleness` when the freshness bar is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/specialties/{code}/by-state": { "get": { "tags": [ "Specialties" ], "summary": "Per-state density for one specialty", "description": "Returns 51 rows (50 states + DC) with per-field provenance.\n\n**Optional `subspecialty` filter (§193).** When supplied, the response is recomputed against NPPES providers whose `taxonomy_codes` array includes the requested NUCC code. Counts, `per_100k`, `rank_density`, and `quartile` are recomputed from the filtered slice. The parent study's underserved threshold doesn't transfer, so filtered rows always carry `underserved: false`.\n\nSupported `subspecialty` codes per primary specialty (built from §183 / §188 specialty-study configs — same taxonomies the underlying ingest scoped to):\n\n- **cardiology**: single-taxonomy ingest (`207RC0000X` — Internal Medicine, Cardiovascular Disease (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **dermatology** (5 taxonomies):\n - `207N00000X` — Dermatology (parent)\n - `207ND0900X` — Dermatopathology\n - `207NI0002X` — Clinical & Laboratory Dermatological Immunology\n - `207NP0225X` — Pediatric Dermatology\n - `207NS0135X` — Procedural Dermatology / MOHS\n- **gastroenterology**: single-taxonomy ingest (`207RG0100X` — Internal Medicine, Gastroenterology). `?subspecialty=` either matches the parent or returns zero rows.\n- **neurology**: single-taxonomy ingest (`2084N0400X` — Psychiatry & Neurology, Neurology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **obgyn** (3 taxonomies):\n - `207V00000X` — Obstetrics & Gynecology (parent)\n - `207VX0000X` — Obstetrics & Gynecology, Obstetrics\n - `207VG0400X` — Obstetrics & Gynecology, Gynecology\n- **oncology**: single-taxonomy ingest (`207RX0202X` — Internal Medicine, Medical Oncology). `?subspecialty=` either matches the parent or returns zero rows.\n- **ophthalmology**: single-taxonomy ingest (`207W00000X` — Ophthalmology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **orthopedic**: single-taxonomy ingest (`207X00000X` — Orthopaedic Surgery (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **otolaryngology**: single-taxonomy ingest (`207Y00000X` — Otolaryngology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **pediatrics** (20 taxonomies):\n - `208000000X` — Pediatrics (parent)\n - `2080A0000X` — Pediatrics, Adolescent Medicine\n - `2080P0006X` — Pediatrics, Developmental — Behavioral Pediatrics\n - `2080P0008X` — Pediatrics, Neurodevelopmental Disabilities\n - `2080N0001X` — Pediatrics, Neonatal-Perinatal Medicine\n - `2080P0202X` — Pediatrics, Pediatric Cardiology\n - `2080P0203X` — Pediatrics, Child Abuse Pediatrics\n - `2080P0204X` — Pediatrics, Pediatric Emergency Medicine\n - `2080P0205X` — Pediatrics, Pediatric Hematology-Oncology\n - `2080P0206X` — Pediatrics, Pediatric Endocrinology\n - `2080P0207X` — Pediatrics, Pediatric Hematology-Oncology (alt)\n - `2080P0208X` — Pediatrics, Pediatric Infectious Diseases\n - `2080P0210X` — Pediatrics, Pediatric Pulmonology\n - `2080P0214X` — Pediatrics, Pediatric Rheumatology\n - `2080P0216X` — Pediatrics, Pediatric Sports Medicine\n - `2080I0007X` — Pediatrics, Pediatric Infectious Diseases (alt)\n - `2080S0010X` — Pediatrics, Sleep Medicine\n - `2080S0012X` — Pediatrics, Sports Medicine\n - `2080T0002X` — Pediatrics, Pediatric Transplant Hepatology\n - `2080H0002X` — Pediatrics, Hospice and Palliative Medicine\n- **psychiatry**: single-taxonomy ingest (`2084P0800X` — Psychiatry (individual provider)). `?subspecialty=` either matches the parent or returns zero rows.\n- **urology**: single-taxonomy ingest (`208800000X` — Urology (parent)). `?subspecialty=` either matches the parent or returns zero rows.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string", "example": "dermatology" } }, { "in": "query", "name": "subspecialty", "required": false, "description": "NUCC taxonomy code to filter on. Must be registered for the primary specialty (see endpoint description). Example: `207NS0135X` (Procedural Dermatology / MOHS) for primary `dermatology`.", "schema": { "type": "string", "example": "207NS0135X" } }, { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "responses": { "200": { "description": "Per-state rows with provenance. When `subspecialty` is supplied, `meta.subspecialty_filter` is populated with the applied code, display name, and matched record count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecialtyStateRow" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Bad request — most commonly `invalid_subspecialty` when the supplied code is not registered for the primary specialty, or `invalid_max_staleness` when the freshness bar is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/specialties/{code}/by-county": { "get": { "tags": [ "Specialties" ], "summary": "Per-county aggregate (state-level density proxy)", "description": "NPPES does not publish a county-level field of practice in its public API. Responses surface the parent state's density figure with the county context preserved in `meta.geo_scope_note`. Mirrors the §191 Access Gap Lookup Tool's honesty disclosure.\n\n**Optional `subspecialty` filter (§193).** Same semantics as `/specialties/{code}/by-state` — the recomputed slice is intersected with the requested state, and the resulting state-level row is returned in `data.state_level_supply`.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string", "example": "CA" } }, { "in": "query", "name": "county_fips", "required": true, "schema": { "type": "string", "example": "06037" } }, { "in": "query", "name": "subspecialty", "required": false, "description": "NUCC taxonomy code to filter on. See `/specialties/{code}/by-state` description for the per-primary registry.", "schema": { "type": "string", "example": "207NS0135X" } }, { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "responses": { "200": { "description": "County-context state-level aggregate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/states/{state}/coverage": { "get": { "tags": [ "States" ], "summary": "Combined per-specialty coverage for one state", "parameters": [ { "in": "path", "name": "state", "required": true, "schema": { "type": "string", "example": "CA" } }, { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "responses": { "200": { "description": "Per-specialty rollup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Bad request — `invalid_max_staleness` when the freshness bar is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/providers/{npi}": { "get": { "tags": [ "Providers" ], "summary": "Single provider lookup by NPI", "parameters": [ { "in": "path", "name": "npi", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" } }, { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "responses": { "200": { "description": "Provider record with the per-field provenance available to the response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProviderRecord" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Bad request — `invalid_max_staleness` when the freshness bar is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/npi/{npi}": { "get": { "operationId": "getNpiEntityResolution", "summary": "Cross-dataset entity resolution by NPI", "description": "Returns the source blocks available for an NPI from NPPES, OIG LEIE, PECOS, QPP MIPS, CMS Open Payments, and SAM.gov. A block can be absent, and provenance fields within a block can be null. Exclusion booleans are nullable: a no-match is emitted only when the internal coverage guard reports reconciled `current`; that state does not assert same-day upstream freshness. Stale or unreconciled coverage returns `determination: indeterminate` and is not a clearance.\n\nRequires `Authorization: Bearer fnt_...` and uses the key's configured limits.\n\nCaching: `Cache-Control: no-store`; a newer comparable exclusion artifact can invalidate a prior negative immediately.", "tags": [ "NpiEntityResolution" ], "parameters": [ { "name": "npi", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$", "example": "1174785802" }, "description": "10-digit NPI (National Provider Identifier)." }, { "$ref": "#/components/parameters/MaxStaleness" }, { "$ref": "#/components/parameters/MaxStalenessMode" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Resolved provider record with the available source blocks and nullable per-source provenance fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "npi": { "type": "string", "example": "1174785802" }, "resolved_at": { "type": "string", "format": "date-time" }, "authenticated": { "type": "boolean" }, "sources": { "type": "object", "description": "One block per supported federal source. A block exposes `data` (null if not found / not ingested) and a nullable `provenance` object; populated values vary by source and response. Sources: nppes, oig_leie, pecos, qpp_mips, open_payments, sam_gov." }, "composite": { "type": "object", "properties": { "active_and_clean": { "type": "boolean", "nullable": true, "description": "Null when exclusion coverage is stale or indeterminate; never true without current coverage." }, "sources_resolved": { "type": "integer" }, "field_confidence_min": { "type": "number" }, "_methodology": { "type": "string" } } }, "exclusion_screen": { "type": "object", "properties": { "excluded": { "type": "boolean", "nullable": true }, "compromised_anywhere": { "type": "boolean", "nullable": true }, "coverage": { "$ref": "#/components/schemas/ExclusionCoverage" }, "coverage_status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "determination": { "type": "string", "enum": [ "match", "no_match", "indeterminate" ] } } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "NPI is not exactly 10 digits, or `invalid_max_staleness` when the freshness bar is malformed." }, "404": { "description": "NPI not found in CMS NPPES NPI Registry." }, "409": { "$ref": "#/components/responses/StaleRejected" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "CMS NPPES could not answer reliably because its upstream request failed or returned an invalid payload. The lookup is indeterminate, not a not-found result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "nppes_unavailable", "message": "CMS NPPES is temporarily unavailable; this provider lookup is indeterminate, not a not-found result." }, "meta": { "request_id": "req_8Fk2pQ", "api_version": "v1" } } } } } } } }, "/npi/{npi}/risk": { "get": { "operationId": "getNpiExclusionSignals", "summary": "Exact OIG exclusion signals for one NPI", "description": "API-key-only exact NPI matching against OIG LEIE serving rows. This endpoint returns public-record exclusion signals and the provenance fields available to the match; it does not compute a risk score or certification. A zero-signal result is returned only when the endpoint's coverage guard reports `current` after reconciling the serving table to its comparable internal artifact; that status does not assert same-day upstream freshness. When coverage trails or cannot reconcile, HTTP 503 returns `determination: indeterminate`, coverage evidence, and `Cache-Control: private, no-store`; that response is not a clearance. Positive signals remain HTTP 200 and disclose the coverage status.", "tags": [ "NpiEntityResolution" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "npi", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$", "example": "1689095580" }, "description": "10-digit NPI (National Provider Identifier)." } ], "responses": { "200": { "description": "One or more exact exclusion signals, or a zero-signal result when the endpoint's internal coverage guard reports reconciled current coverage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "npi", "signals", "checked_at", "from_cache", "determination", "coverage_status", "coverage", "_provenance", "meta" ], "properties": { "npi": { "type": "string", "pattern": "^\\d{10}$" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "npi": { "type": "string" }, "signal_type": { "type": "string", "enum": [ "exclusion" ] }, "evidence": { "type": "object" }, "detected_at": { "type": "string", "format": "date-time" } } } }, "checked_at": { "type": "string", "format": "date-time" }, "from_cache": { "type": "boolean" }, "determination": { "type": "string", "enum": [ "match", "no_match", "indeterminate" ] }, "coverage_status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "coverage": { "$ref": "#/components/schemas/ExclusionCoverage" }, "warning": { "type": "string" }, "_provenance": { "type": "object" }, "meta": { "type": "object" } } } } } }, "400": { "description": "NPI is not exactly 10 digits." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Serving-table retrieval failed." }, "503": { "description": "Zero-signal result with stale or unreconciled OIG coverage. The response uses the same body schema as 200, with `determination: indeterminate`; no negative determination was made.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/entity/ccn/{ccn}": { "get": { "tags": [ "Entity Graph" ], "operationId": "getCcnNpiCrosswalk", "summary": "Resolve a canonical CCN-to-NPI crosswalk link", "description": "Returns a crosswalk link when one is available. This is not a facility profile, ownership record, or Care Compare quality response.", "security": [], "parameters": [ { "name": "ccn", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-Za-z]{6}$|^[0-9A-Za-z]{10}$", "example": "050441" }, "description": "Six- or ten-character CMS Certification Number." } ], "responses": { "200": { "description": "Canonical CCN-to-NPI link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ccn", "npi", "link_method", "link_confidence", "link_tier" ], "properties": { "ccn": { "type": "string" }, "npi": { "type": "string", "pattern": "^\\d{10}$" }, "link_method": { "type": "string" }, "link_confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "link_tier": { "type": "string", "enum": [ "deterministic", "candidate_unreviewed" ] }, "source_table": { "type": "string" }, "methodology_version": { "type": "string" }, "attested_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "400": { "description": "CCN format is invalid." }, "404": { "description": "No canonical crosswalk link is available for this CCN." } } } }, "/quality": { "get": { "tags": [ "Quality" ], "operationId": "getDataQualityScorecard", "summary": "Get the Fonteum data-quality scorecard", "description": "Returns completeness, consistency, timeliness, and OIG LEIE match-rate methodology metrics for Fonteum's data operations. status is current only when every required evidence family is present; otherwise status is incomplete and composite_score can be null. Missing measurements are not replaced with historical constants. This endpoint does not return facility-level Care Compare ratings.", "security": [], "responses": { "200": { "description": "Data-quality scorecard.", "content": { "application/json": { "schema": { "type": "object", "required": [ "generated_at", "status", "composite_score", "completeness", "consistency", "timeliness", "oig_leie_match_rate", "_methodology" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "current", "incomplete" ], "description": "current only when every configured completeness and timeliness source, at least one consistency row, and observed OIG byte-match evidence are present; incomplete otherwise." }, "composite_score": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true, "description": "Weighted composite over published evidence families, or null when none has a reproducible value." }, "completeness": { "type": "array", "items": { "type": "object" } }, "consistency": { "type": "array", "items": { "type": "object" } }, "timeliness": { "type": "array", "items": { "type": "object" } }, "oig_leie_match_rate": { "type": "object" }, "_methodology": { "type": "string", "format": "uri" } } } } } } } } }, "/search": { "get": { "tags": [ "Search" ], "operationId": "searchPublicRecords", "summary": "Search public-record entities", "description": "Authenticated JSON lookup across providers, hospitals, trials, studies, and resolved entities. Omit `q` to read the endpoint contract.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Search text. Omit to return the endpoint contract." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 }, "description": "Maximum results per category." } ], "responses": { "200": { "description": "JSON search result groups or the endpoint contract.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Query is empty or malformed." }, "401": { "description": "Missing or invalid Fonteum API key." }, "429": { "description": "API-key quota exceeded." } } }, "post": { "tags": [ "Search" ], "operationId": "searchProviderRecords", "summary": "Search provider records using a semantic query", "description": "Public per-IP-limited semantic provider search. The response is a Server-Sent Event stream with `meta`, `result`, optional `error`, and `complete` frames; it is not the canonical cross-vertical MCP search surface.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 4000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } } } } }, "responses": { "200": { "description": "Server-Sent Event stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Query is missing, malformed, or too long." }, "401": { "description": "Missing or invalid Fonteum API key." }, "429": { "description": "Per-IP search rate limit exceeded." } } } }, "/mcp/search-records": { "get": { "tags": [ "Search" ], "operationId": "searchHostedMcpRecords", "summary": "Search records with the hosted MCP schema", "description": "REST bridge for the `fonteum_search_providers` MCP tool and source-only @fonteum/mcp 0.5.0 contract. Requires a healthcare vertical and state; it returns the same dated source-context envelope as hosted MCP. This is distinct from the semantic SSE `/search` endpoint.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "vertical", "required": true, "schema": { "type": "string", "example": "dermatologists" }, "description": "Healthcare vertical slug." }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "example": "TX" }, "description": "Two-letter USPS state code." }, { "in": "query", "name": "county", "required": false, "schema": { "type": "string", "example": "Travis" }, "description": "Optional county context." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum records to return." } ], "responses": { "200": { "description": "Hosted MCP search result envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "provenance", "source_file", "as_of_date", "snapshot_digest", "verifiable_url" ], "properties": { "data": { "type": "object" }, "provenance": { "type": "object" }, "source_file": { "type": "string", "nullable": true, "description": "Exact retained source filename when one file represents the response; null for composite results or when no retained file is identified." }, "as_of_date": { "type": "string", "nullable": true, "description": "Source publish or snapshot date when one date represents the response; null for composite results with dates in nested source blocks or when no source date is available." }, "snapshot_digest": { "type": "string", "nullable": true, "description": "Digest of an identified retained snapshot object; null for composite results with digests in nested source blocks or when unavailable, and never a per-fact signature or live-chain-head substitute." }, "verifiable_url": { "type": "string", "format": "uri", "description": "Public source, methodology, or retained-snapshot re-check URL appropriate to the response." } } } } } }, "400": { "description": "Missing or invalid hosted MCP search input." }, "401": { "description": "Missing or invalid Fonteum API key." } } } }, "/mcp/dataset-info": { "get": { "tags": [ "Methodology" ], "operationId": "getHostedMcpDatasetInfo", "summary": "Get the hosted MCP methodology and source catalog", "description": "REST bridge for the no-argument `fonteum_get_dataset_info` MCP tool and source-only @fonteum/mcp 0.5.0 contract. Returns the current methodology, dated source context, and public multi-vertical source catalog.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Hosted MCP dataset information envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "provenance", "source_file", "as_of_date", "snapshot_digest", "verifiable_url" ], "properties": { "data": { "type": "object", "properties": { "methodology_version": { "type": "string" }, "methodology_url": { "type": "string", "format": "uri" }, "platform_coverage": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PlatformCoverage" } ] }, "source_catalog_entry_count": { "type": "integer", "minimum": 0, "description": "Entries in the generated MCP catalog; not a loaded or live platform-coverage count." }, "sources": { "type": "array", "items": { "type": "object" } } } }, "provenance": { "type": "object" }, "source_file": { "type": "string", "nullable": true, "description": "Exact retained source filename when one file represents the response; null for composite results or when no retained file is identified." }, "as_of_date": { "type": "string", "nullable": true, "description": "Source publish or snapshot date when one date represents the response; null for composite results with dates in nested source blocks or when no source date is available." }, "snapshot_digest": { "type": "string", "nullable": true, "description": "Digest of an identified retained snapshot object; null for composite results with digests in nested source blocks or when unavailable, and never a per-fact signature or live-chain-head substitute." }, "verifiable_url": { "type": "string", "format": "uri", "description": "Public source, methodology, or retained-snapshot re-check URL appropriate to the response." } } } } } }, "401": { "description": "Missing or invalid Fonteum API key." } } } }, "/mcp/recheck": { "get": { "tags": [ "Methodology" ], "operationId": "getHostedMcpRecheck", "summary": "Re-check a record with the hosted MCP schema", "description": "REST bridge for the `fonteum_recheck_snapshot` MCP tool and source-only @fonteum/mcp 0.5.0 contract. Returns the hosted re-check envelope, including available source_file, as_of_date, snapshot_digest, and verifiable_url values for an identified retained snapshot; it is not the narrower attestation-check response.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "snapshot_id", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 7 }, "description": "Optional positive snapshot id. Omit for the current chain head." } ], "responses": { "200": { "description": "Hosted MCP re-check envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "provenance", "source_file", "as_of_date", "snapshot_digest", "verifiable_url" ], "properties": { "data": { "type": "object" }, "provenance": { "type": "object" }, "source_file": { "type": "string", "nullable": true, "description": "Exact retained source filename when one file represents the response; null for composite results or when no retained file is identified." }, "as_of_date": { "type": "string", "nullable": true, "description": "Source publish or snapshot date when one date represents the response; null for composite results with dates in nested source blocks or when no source date is available." }, "snapshot_digest": { "type": "string", "nullable": true, "description": "Digest of an identified retained snapshot object; null for composite results with digests in nested source blocks or when unavailable, and never a per-fact signature or live-chain-head substitute." }, "verifiable_url": { "type": "string", "format": "uri", "description": "Public source, methodology, or retained-snapshot re-check URL appropriate to the response." } } } } } }, "400": { "description": "snapshot_id is not a positive integer." }, "401": { "description": "Missing or invalid Fonteum API key." } } } }, "/methodology/{dataset}": { "get": { "tags": [ "Methodology" ], "summary": "Methodology metadata for a dataset", "parameters": [ { "in": "path", "name": "dataset", "required": true, "schema": { "type": "string", "example": "nppes-specialty-supply" } } ], "responses": { "200": { "description": "Methodology metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sources": { "get": { "tags": [ "Sources" ], "summary": "List public source-registry entries", "description": "Returns the public source-registry entries exposed by this endpoint. An entry can carry slug, authority, tier, status, publisher cadence, and official URL; those fields describe the registry entry and do not establish a fresh load. Response-level provenance fields can be null. Public, read-only.", "security": [], "responses": { "200": { "description": "Source-registry response with a nullable provenance envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "example": "nppes" }, "short_name": { "type": "string", "example": "CMS NPPES" }, "display_name": { "type": "string" }, "authority": { "type": "string", "example": "Centers for Medicare & Medicaid Services" }, "family": { "type": "string" }, "tier": { "type": "string" }, "status": { "type": "string" }, "refresh_cadence": { "type": "string", "example": "Quarterly" }, "official_url": { "type": "string", "format": "uri" } } } }, "public_catalog_entry_count": { "type": "integer", "description": "Number of entries in this public source catalog response." }, "platform_coverage": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PlatformCoverage" } ] }, "active_source_family_count": { "type": "integer", "minimum": 0, "nullable": true, "deprecated": true, "description": "Deprecated v1 alias of platform_coverage.sources_integrated, as of active_source_family_count_as_of. Null when the dated platform snapshot is unavailable." }, "active_source_family_count_as_of": { "type": "string", "format": "date", "nullable": true, "deprecated": true }, "active_source_family_count_definition": { "type": "string", "deprecated": true } } }, "provenance": { "type": "object", "description": "Nullable response-level provenance fields." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } }, "/bulk/manifest.json": { "get": { "tags": [ "Bulk" ], "summary": "List currently published bulk files", "description": "The complete bulk-download contract. Every listed entry names the exact URL, filename, media type, and CSV columns that Fonteum currently delivers. Do not construct a bulk URL from a source identifier alone.", "security": [], "responses": { "200": { "description": "Current manifest of tested bulk files.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sources" ], "properties": { "schema_version": { "type": "string", "example": "v1" }, "generated_at": { "type": "string", "format": "date-time" }, "registered_source_detail_page_count": { "type": "integer" }, "platform_coverage": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PlatformCoverage" } ] }, "active_source_family_count": { "type": "integer", "minimum": 0, "nullable": true, "deprecated": true, "description": "Deprecated v1 alias of platform_coverage.sources_integrated, as of active_source_family_count_as_of. Null when the dated platform snapshot is unavailable." }, "active_source_family_count_as_of": { "type": "string", "format": "date", "nullable": true, "deprecated": true }, "active_source_family_count_definition": { "type": "string", "deprecated": true }, "bulk_source_count": { "type": "integer" }, "live_source_count": { "type": "integer" }, "cached_count": { "type": "integer" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "source_id", "format", "filename", "columns", "source_url", "generated_at", "limitation", "latest_snapshot_url" ], "properties": { "source_id": { "type": "string", "example": "cms-pos-facilities" }, "display_name": { "type": "string" }, "cadence": { "type": "string" }, "license": { "type": "string" }, "source_url": { "type": "string", "format": "uri", "description": "Official upstream source for the emitted public-record fields." }, "generated_at": { "type": "string", "format": "date-time", "description": "When Fonteum generated this live-query manifest entry." }, "limitation": { "type": "string", "description": "Qualification for a live query rather than an immutable source-file snapshot." }, "delivery": { "type": "string", "enum": [ "live-query", "cached-snapshot" ] }, "format": { "type": "string", "example": "application/gzip" }, "filename": { "type": "string", "example": "cms-pos-facilities.csv.gz" }, "columns": { "type": "array", "items": { "type": "string" } }, "latest_snapshot_url": { "type": "string", "format": "uri" }, "manifest_url": { "type": "string", "format": "uri" } } } } } } } } } } } }, "/bulk/cms-pos-facilities/latest.csv.gz": { "get": { "tags": [ "Bulk" ], "summary": "Download the CMS POS facility directory as gzip CSV", "description": "The current CMS Provider of Services facility directory. Read `/bulk/manifest.json` before downloading to obtain its current columns and delivery metadata.", "security": [], "responses": { "200": { "description": "gzip-compressed CSV whose header matches the columns listed in the bulk manifest.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "Attachment filename from the current manifest entry." }, "X-Fonteum-Source-Url": { "schema": { "type": "string", "format": "uri" }, "description": "Official upstream CMS POS source for the emitted fields." }, "X-Fonteum-Generated-At": { "schema": { "type": "string", "format": "date-time" }, "description": "When this live-query download began generating." }, "X-Fonteum-Limitation": { "schema": { "type": "string" }, "description": "Qualification that the file is a live query, not an immutable upstream archive." } }, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/evidence-query": { "post": { "tags": [ "Evidence Query" ], "summary": "Provenance-grounded natural-language Q&A (§197)", "description": "POST a natural-language question about a supported U.S. healthcare-provider supply dataset. Returns a short answer plus the evidence fields available to the selected resolver, which can include source URL, observation timestamp, methodology, confidence, and limitations. Fields can be null when the audit-pack registry does not supply them.\n\n**Pipeline (SQL-injection-safe by construction):**\n1. Pre-flight filters reject prompt-injection signatures, payment/claims questions, predictions, vendor comparisons, and single-provider PII fishing before any LLM call.\n2. Anthropic Sonnet maps the question to a strict whitelist intent (dataset slug + state code + intent kind) via tool-use; the input schema constrains output to the registered enums. Output is then runtime-validated.\n3. A typed resolver dispatches to hand-written, pre-existing data accessors. The classifier output never produces SQL — there is no `query()` call that concatenates LLM output into a query string anywhere in the pipeline.\n4. Available claim evidence is attached from the audit-pack registry; a second LLM call writes the summary constrained to the resolver's exact numbers, with a deterministic-template fallback.\n\n**County-scope honesty:** NPPES has no public county-of-practice field. Queries scoped to a county return state-level supply with `geo_widened: true` flagged in the answer and an explicit limitation in the evidence trail.\n\n**Refusal codes:** `out_of_scope`, `predictions`, `payment_data`, `competitor_compare`, `individual_provider_lookup`, `prompt_injection`, `classification_failed`. Refusals return HTTP 200 with `status: \"refusal\"` and a machine-readable `refusal.code`.\n\nDemo (no auth, 10 queries / 24h per IP): POST `/api/evidence-query/demo` with the same body shape.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1500, "example": "How many active dermatologists practice in Texas, and how is that number sourced?" }, "options": { "type": "object", "properties": { "max_evidence_items": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } } } } } } }, "responses": { "200": { "description": "Answer + evidence trail (or refusal).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "refusal" ] }, "answer": { "type": "object", "nullable": true, "properties": { "summary": { "type": "string" }, "value": { "type": "number", "nullable": true }, "unit": { "type": "string", "nullable": true }, "dataset": { "type": "string" }, "dataset_slug": { "type": "string" }, "methodology_version": { "type": "string", "example": "v2026.05.0" }, "geo_widened": { "type": "boolean" } } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "claim": { "type": "string" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "tier": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "last_checked": { "type": "string", "format": "date-time" }, "artifact_snapshot_at": { "type": "string", "format": "date-time", "description": "Aggregate/static artifact snapshot represented by the claim; not a publisher release or Fonteum content-change timestamp." }, "timestamp_basis": { "type": "string", "enum": [ "artifact_snapshot" ] }, "confidence": { "type": "number" } } }, "methodology": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } } } } }, "refusal": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Malformed request (invalid JSON, missing query, or query too long)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{dataset}/llm-ready": { "get": { "tags": [ "Exports" ], "summary": "AI-native LLM-ready export for a registered dataset slug (§198)", "description": "Returns a supported registered dataset slug as chunked text plus the structured, methodology, and citation fields available for that exporter, in one of three formats:\n\n- `?format=json` (default) — a RAG envelope with `dataset`, optional `narrative`, `chunks[]`, and `meta`.\n- `?format=ndjson` — newline-delimited JSON with a `_dataset_meta` header followed by chunks.\n- `?format=text-blocks` — plain text with methodology, chunk, and citation delimiters.\n\nChunk fields and source/date metadata vary by registered dataset; inspect the selected response rather than assuming a universal provenance tuple. Narrative generation and cache headers are exporter-specific. Embeddings are omitted; consumers supply their own embedding model and storage.\n\nPossible response headers include `X-Methodology-Version`, `X-Last-Refreshed` (deprecated; empty when canonical content-change evidence is unavailable), `X-Source-Release-Date` (empty when publisher release evidence is unavailable), `X-Artifact-Snapshot-Date`, `X-Total-Chunks`, and `X-Narrative-Cache-Hit`. Artifact snapshots never populate the refreshed or source-release headers.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "dataset", "required": true, "schema": { "type": "string", "example": "dermatology-supply" }, "description": "Audit-pack dataset slug. One of the 17 registered slugs: dermatology-supply, psychiatry-supply, cardiology-supply, obgyn-supply, pediatrics-supply, neurology-supply, oncology-supply, orthopedic-supply, ophthalmology-supply, gastroenterology-supply, urology-supply, otolaryngology-supply, chiropractor-supply, nursing-home-quality, dialysis-quality, home-health-quality, hospice-availability." }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "json", "ndjson", "text-blocks" ], "default": "json" }, "description": "Output format. Default `json`." } ], "responses": { "200": { "description": "Dataset export. Content-Type varies by format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "schema_version": { "type": "string", "example": "1.0" }, "dataset": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" }, "one_liner": { "type": "string" }, "methodology_version": { "type": "string", "example": "v2026.05.0" }, "snapshot_date": { "type": "string", "format": "date" }, "refresh_cadence": { "type": "string" }, "source_families": { "type": "array", "items": { "type": "string" } } } }, "narrative": { "type": "string", "nullable": true }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "data": { "type": "object" }, "methodology": { "type": "object", "properties": { "version": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "last_checked": { "type": "string", "format": "date-time" }, "cadence": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "citation": { "type": "string" }, "chunk_type": { "type": "string", "enum": [ "national", "state", "underserved", "dataset_meta" ] } } } }, "meta": { "type": "object" } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "One JSON object per line. First line is `_line_type: dataset_meta`; subsequent lines are `_line_type: chunk` with the same per-chunk shape as the JSON format." } }, "text/plain": { "schema": { "type": "string", "description": "Plain text with delimited blocks: `--- METHODOLOGY ---` header, optional `--- NARRATIVE ---`, then `--- CHUNK ---` blocks, ending with `--- CITATION FOOTER ---`." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audit-pack": { "get": { "tags": [ "Audit Pack" ], "summary": "List all available Audit Packs (§194)", "description": "Returns a catalog of all 16 Audit Packs (12 NPPES specialty supply studies + 4 CMS Care Compare facility studies). Each entry includes the dataset slug, current methodology version, refresh cadence, and direct links to the public web view, the PDF download, and the JSON download. Compliance-tool integrations consume this endpoint to keep their internal Audit Pack catalog in sync.", "responses": { "200": { "description": "Catalog list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audit-pack/{slug}": { "get": { "tags": [ "Audit Pack" ], "summary": "Authenticated Audit Pack metadata + per-field provenance map (§194)", "description": "Returns the full Audit Pack JSON envelope (schema_version 1.0) for a single dataset — methodology version, per-field provenance map, reproducibility steps, limitations stack, version history, compliance Q&A. The same shape is downloadable publicly without auth at GET /api/audit-pack/{slug}/json (and as a PDF at GET /api/audit-pack/{slug}/pdf); this v1 endpoint is for compliance-tool integrations that already auth against the API.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "example": "dermatology-supply" } } ], "responses": { "200": { "description": "Audit Pack envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }