{ "openapi": "3.1.0", "info": { "title": "Fonteum API", "version": "1.6.0", "summary": "Source-provenanced public records across supported domains.", "description": "The Fonteum API includes FHIR R4 provider routes (`/api/fhir`), JSON REST routes (`/api/v1`) for the entity graph, public-record search, source-specific retained history, and structured cited answers (`/ask`), plus an AI-native RAG export (`/api/export`). Fonteum covers healthcare, federal procurement, sanctions and watchlists, enforcement, and corporate and securities records. Current platform coverage is available from the dated platform-stats endpoint; integrated registry status does not by itself indicate loaded or complete coverage, and not every source supplies NPI or retained history. Provenance fields are nullable by source and response; no provenance fact currently links deterministically to a signature.\n\nOperations marked with `security: []` are explicitly public. Other operations require a Fonteum API key as `Authorization: Bearer fnt_...`; try the live read-only sample `fnt_DEMO_PUBLIC_V1` or create an account at https://fonteum.com/account/signup for an issued key.", "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", "description": "Fonteum production" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "FHIR", "description": "FHIR R4 provider resources + Bulk Data $export." }, { "name": "Entity Graph", "description": "Cross-source identity resolution over the provider graph." }, { "name": "Search", "description": "Search across the provider, facility, trial, study, and entity indexes supported by the endpoint." }, { "name": "History", "description": "Source-specific point-in-time reads and diffs where retained row versions exist." }, { "name": "Ask", "description": "Deterministic, cited question-answering (ask/v1)." }, { "name": "Export", "description": "AI-native RAG export of studies, datasets, and key pages." }, { "name": "Platform truth", "description": "Dated platform-count observations and their limitations." }, { "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" }, "next_refresh_eta": { "type": [ "string", "null" ], "format": "date-time" }, "cadence": { "type": "string" } } }, "PlatformCoverage": { "type": "object", "description": "Query-derived platform coverage from one public.platform_stats_snapshots row. Null at the response property when no post-crosswalk snapshot is available.", "required": [ "as_of_date", "captured_at", "sources_live", "sources_integrated", "states_covered", "definitions", "provenance" ], "properties": { "as_of_date": { "type": "string", "format": "date" }, "captured_at": { "type": "string", "format": "date-time" }, "sources_live": { "type": "integer", "minimum": 0, "description": "Distinct active registered sources with a crosswalk-resolved snapshot dated in the preceding 45 days." }, "sources_integrated": { "type": "integer", "minimum": 0, "description": "Active production source-registry rows. Integration does not imply a loaded or fresh source." }, "states_covered": { "type": "integer", "minimum": 0, "description": "Distinct state values represented in the state Medicaid exclusions serving table." }, "definitions": { "type": "object", "required": [ "sources_live", "sources_integrated", "states_covered" ], "properties": { "sources_live": { "type": "string" }, "sources_integrated": { "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" } } } } }, "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", "null" ], "format": "date" }, "attested_as_of": { "type": [ "string", "null" ], "format": "date" }, "attestation_snapshot_id": { "type": [ "integer", "null" ] }, "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", "null" ], "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", "null" ], "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", "null" ] }, "as_of": { "type": [ "string", "null" ] }, "attestation_id": { "type": [ "integer", "null" ], "description": "Snapshot id when a specific snapshot is in scope; otherwise the live chain-head link index." }, "chain_head_hash": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "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", "null" ] }, "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", "null" ], "minimum": 1 }, "bitcoin_block_height": { "type": [ "integer", "null" ], "minimum": 0 }, "provider": { "type": [ "string", "null" ] }, "block_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "submitted_at": { "type": "string", "format": "date-time" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "quarantine_reason": { "type": [ "string", "null" ] } } }, "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", "null" ], "format": "date-time" }, "age_seconds": { "type": [ "number", "null" ], "minimum": 0 }, "stale_after_seconds": { "type": "integer", "minimum": 1 } } }, "chain_head_anchor": { "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/ChainAnchorSummary" } ] }, "latest_mainnet_verified": { "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/ChainAnchorSummary" } ] }, "latest_submission_at": { "type": [ "string", "null" ], "format": "date-time" }, "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", "null" ], "pattern": "^[0-9a-f]{64}$" }, "signature": { "type": [ "string", "null" ] }, "key_id": { "type": [ "string", "null" ] }, "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", "null" ], "allOf": [ { "$ref": "#/components/schemas/SignedTreeHead" } ] }, "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": { "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", "null" ], "format": "date", "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", "null" ] }, "sla_hours": { "type": [ "integer", "null" ] }, "age_hours": { "type": [ "integer", "null" ] }, "age_days": { "type": [ "integer", "null" ] }, "within_sla": { "type": [ "boolean", "null" ] }, "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", "null" ] }, "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" } } }, "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" } } }, "RagChunkPage": { "type": "object", "description": "A page of citation-ready RAG chunks (rag-chunks/v1).", "properties": { "methodology_version": { "type": "string", "example": "rag-chunks/v1" }, "corpus_snapshot": { "type": "string", "example": "2026-06-14" }, "total": { "type": "integer", "description": "Total chunks in the full corpus." }, "limit": { "type": "integer", "description": "Effective page size after clamping." }, "cursor": { "type": "integer", "description": "Start index of this page." }, "next_cursor": { "type": [ "integer", "null" ], "description": "Start index of the next page, or null at the end." }, "chunk_count": { "type": "integer" }, "chunks": { "type": "array", "items": { "$ref": "#/components/schemas/RagChunk" } } } }, "RagChunk": { "type": "object", "description": "One retrieval-ready, provenance-carrying chunk.", "properties": { "chunk_id": { "type": "string", "example": "source:nppes#overview", "description": "Stable id — safe as a vector-store primary key." }, "dataset_id": { "type": "string", "description": "Fonteum dataset slug (matches data_sources.slug)." }, "title": { "type": "string" }, "section": { "type": "string", "enum": [ "overview", "limitations" ] }, "text": { "type": "string", "description": "Citation-ready prose templated from the registry." }, "cite": { "type": "string", "description": "Stable human-readable citation string." }, "source_url": { "type": "string", "format": "uri" }, "token_estimate": { "type": "integer" }, "provenance": { "type": "object", "description": "Source-specific provenance fields; unavailable fields can be null." } } }, "FhirResource": { "type": "object", "description": "A FHIR R4 resource. Available Fonteum source tags can appear on `meta.tag`.", "properties": { "resourceType": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" } }, "additionalProperties": true }, "FhirBundle": { "type": "object", "description": "FHIR R4 searchset Bundle.", "properties": { "resourceType": { "type": "string", "enum": [ "Bundle" ] }, "type": { "type": "string", "example": "searchset" }, "total": { "type": "integer" }, "link": { "type": "array", "items": { "type": "object" } }, "entry": { "type": "array", "items": { "type": "object", "properties": { "fullUrl": { "type": "string" }, "resource": { "$ref": "#/components/schemas/FhirResource" } } } } } }, "FhirCapabilityStatement": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "CapabilityStatement" ] }, "status": { "type": "string" }, "fhirVersion": { "type": "string", "example": "4.0.1" }, "rest": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": true }, "FhirOperationOutcome": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "OperationOutcome" ] }, "issue": { "type": "array", "items": { "type": "object" } } } }, "EntityResolution": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "entity": { "$ref": "#/components/schemas/EntityNode" }, "identifier": { "type": "object" }, "entity_url": { "type": "string", "format": "uri" }, "methodology_version": { "type": "string", "example": "v2026.05.0" } } }, "EntityNode": { "type": "object", "properties": { "entity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "display_name": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string" } } }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "source_table": { "type": "string" }, "link_method": { "type": "string" }, "link_confidence": { "type": "number" } } } }, "edges": { "type": "array", "items": { "type": "object" } }, "edges_truncated": { "type": "boolean" }, "methodology_version": { "type": "string", "example": "v2026.05.0" } } }, "AskAnswer": { "type": "object", "properties": { "question": { "type": "string", "enum": [ "ownership", "sanctions", "payments" ] }, "subject": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" } } }, "answer_text": { "type": "string" }, "facts": { "type": "array", "items": { "type": "object", "properties": { "fact_type": { "type": "string" }, "statement": { "type": "string" }, "confidence": { "type": "number" }, "provenance": { "type": "object", "description": "Source-specific provenance fields; unavailable fields can be null." } } } }, "fact_count": { "type": "integer" }, "facts_truncated": { "type": "boolean" }, "citations": { "type": "array", "items": { "type": "object" } }, "exclusion_coverage": { "$ref": "#/components/schemas/ExclusionCoverage" }, "coverage_status": { "type": "string", "enum": [ "current", "coverage_stale", "indeterminate" ] }, "determination": { "type": "string", "enum": [ "match", "no_match", "indeterminate" ] }, "methodology_version": { "type": "string", "example": "v2026.05.0" } } }, "HistorySnapshot": { "type": "object", "properties": { "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "as_of": { "type": "string", "format": "date-time" }, "claims": { "type": "array", "items": { "type": "object" } }, "claim_count": { "type": "integer" }, "truncated": { "type": "boolean" }, "methodology_version": { "type": "string", "example": "bitemporal-read/v1" } } }, "PlatformStatsObservation": { "type": "object", "description": "Latest usable post-crosswalk platform-stats snapshot. metrics is empty when no usable post-crosswalk snapshot exists; as_of and captured_at are then null, and no compile-time coverage count is substituted.", "required": [ "as_of", "captured_at", "from_fallback", "groups", "metrics" ], "properties": { "as_of": { "type": [ "string", "null" ], "format": "date" }, "captured_at": { "type": [ "string", "null" ], "format": "date-time" }, "from_fallback": { "type": "boolean" }, "groups": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "group", "value", "estimated", "source", "description" ], "properties": { "key": { "type": "string", "enum": [ "sources_live", "sources_integrated", "states_covered", "provenance_claims", "entities", "nppes_providers", "part_d_records", "open_payments", "state_licenses", "sam_exclusions", "sam_agencies", "oig_leie", "state_exclusions", "clinical_trials", "nih_projects" ] }, "label": { "type": "string" }, "group": { "type": "string" }, "value": { "type": "integer" }, "estimated": { "type": "boolean" }, "source": { "type": "string" }, "description": { "type": "string" } } } }, "_note": { "type": "string" } } } }, "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" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "paths": { "/api/fhir/metadata": { "get": { "tags": [ "FHIR" ], "summary": "FHIR R4 CapabilityStatement", "description": "FHIR R4 conformance statement. Enumerates the supported Provider resources (Practitioner, Organization, Location, PractitionerRole, HealthcareService) and the Bulk Data $export operation. No authentication required.", "security": [], "responses": { "200": { "description": "CapabilityStatement.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirCapabilityStatement" } } } } } } }, "/api/fhir/.well-known/smart-configuration": { "get": { "tags": [ "FHIR" ], "summary": "SMART on FHIR configuration", "description": "SMART App Launch / Backend Services configuration document (token endpoint, supported grant types, scopes). Used by the Bulk Data $export flow. No authentication required.", "security": [], "responses": { "200": { "description": "SMART configuration.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/fhir/Practitioner": { "get": { "tags": [ "FHIR" ], "summary": "Search Practitioners (individual providers)", "description": "Returns a FHIR R4 searchset Bundle of Practitioner resources sourced from CMS NPPES. Resources can carry the source tags available to that response on `meta.tag`; do not assume a complete provenance tuple. No authentication required.", "security": [], "parameters": [ { "in": "query", "name": "_id", "required": false, "schema": { "type": "string" }, "description": "Practitioner logical id (10-digit NPI)." }, { "in": "query", "name": "identifier", "required": false, "schema": { "type": "string" }, "description": "FHIR token: `system|value` or a bare NPI." }, { "in": "query", "name": "family", "required": false, "schema": { "type": "string" }, "description": "Family-name prefix." }, { "in": "query", "name": "given", "required": false, "schema": { "type": "string" }, "description": "Given-name prefix." }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" }, "description": "Substring across family + given." }, { "in": "query", "name": "_count", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Page size." }, { "in": "query", "name": "_offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Searchset Bundle of Practitioner resources.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "400": { "description": "Invalid search parameter.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/Practitioner/{npi}": { "get": { "tags": [ "FHIR" ], "summary": "Read a Practitioner by NPI", "security": [], "parameters": [ { "in": "path", "name": "npi", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "10-digit NPI." } ], "responses": { "200": { "description": "Practitioner resource.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } } }, "404": { "description": "Not found.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/Organization": { "get": { "tags": [ "FHIR" ], "summary": "Search Organizations", "description": "FHIR R4 searchset Bundle of Organization resources (organization-type NPPES/PECOS records). No authentication required.", "security": [], "parameters": [ { "in": "query", "name": "_id", "required": false, "schema": { "type": "string" }, "description": "Organization logical id (NPI)." }, { "in": "query", "name": "identifier", "required": false, "schema": { "type": "string" }, "description": "Organization NPI." }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" }, "description": "Organization-name substring." }, { "in": "query", "name": "address-state", "required": false, "schema": { "type": "string" }, "description": "2-letter USPS state code." }, { "in": "query", "name": "_count", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Page size." }, { "in": "query", "name": "_offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Searchset Bundle of Organization resources.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "400": { "description": "Invalid search parameter.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/Organization/{id}": { "get": { "tags": [ "FHIR" ], "summary": "Read an Organization by id", "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Organization logical id (NPI)." } ], "responses": { "200": { "description": "Organization resource.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } } }, "404": { "description": "Not found.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/Location": { "get": { "tags": [ "FHIR" ], "summary": "Search Locations (facilities / practice sites)", "description": "FHIR R4 searchset Bundle of Location resources. Supports geo-proximity via `near`. No authentication required.", "security": [], "parameters": [ { "in": "query", "name": "_id", "required": false, "schema": { "type": "string" }, "description": "Location logical id (`-`)." }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" }, "description": "Facility / practice-name substring." }, { "in": "query", "name": "address-state", "required": false, "schema": { "type": "string" }, "description": "USPS state code (exact)." }, { "in": "query", "name": "address-city", "required": false, "schema": { "type": "string" }, "description": "City (case-insensitive exact)." }, { "in": "query", "name": "near", "required": false, "schema": { "type": "string" }, "description": "Geo proximity `lat,lng,radiusKm` (Haversine)." }, { "in": "query", "name": "organization", "required": false, "schema": { "type": "string" }, "description": "Managing Organization (`Organization/`)." }, { "in": "query", "name": "_count", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Page size." }, { "in": "query", "name": "_offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Searchset Bundle of Location resources.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "400": { "description": "Invalid search parameter.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/Location/{id}": { "get": { "tags": [ "FHIR" ], "summary": "Read a Location by id", "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Location logical id." } ], "responses": { "200": { "description": "Location resource.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } } }, "404": { "description": "Not found.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/PractitionerRole": { "get": { "tags": [ "FHIR" ], "summary": "Search PractitionerRoles", "description": "FHIR R4 searchset Bundle linking a Practitioner (NPI) to specialty/role. No authentication required.", "security": [], "parameters": [ { "in": "query", "name": "practitioner", "required": false, "schema": { "type": "string" }, "description": "Practitioner reference / NPI." }, { "in": "query", "name": "_id", "required": false, "schema": { "type": "string" }, "description": "PractitionerRole logical id." }, { "in": "query", "name": "_count", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Page size." }, { "in": "query", "name": "_offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Searchset Bundle of PractitionerRole resources.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "400": { "description": "Invalid search parameter.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/HealthcareService": { "get": { "tags": [ "FHIR" ], "summary": "Search HealthcareServices", "description": "FHIR R4 searchset Bundle of HealthcareService resources (`hs-{NPI}`). No authentication required.", "security": [], "parameters": [ { "in": "query", "name": "_id", "required": false, "schema": { "type": "string" }, "description": "HealthcareService logical id (`hs-`)." }, { "in": "query", "name": "_count", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Page size." }, { "in": "query", "name": "_offset", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Searchset Bundle of HealthcareService resources.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "400": { "description": "Invalid search parameter.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirOperationOutcome" } } } } } } }, "/api/fhir/$export": { "get": { "tags": [ "FHIR" ], "summary": "Bulk Data Access — system-level $export", "description": "FHIR Bulk Data Access ($export). Kicks off an asynchronous NDJSON export and returns 202 with a `Content-Location` polling URL. Requires SMART Backend Services JWT auth or a Fonteum API key (`Authorization: Bearer fnt_...`) with `read` scope.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "_type", "required": false, "schema": { "type": "string" }, "description": "Comma-separated resource types to export." }, { "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "example": "respond-async" } } ], "responses": { "202": { "description": "Export accepted. Poll the `Content-Location` URL." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/fhir/bulk-status/{jobId}": { "get": { "tags": [ "FHIR" ], "summary": "Bulk Data Access — poll export job status", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "type": "string" }, "description": "Export job id returned by $export." } ], "responses": { "200": { "description": "Export complete — manifest of NDJSON output files." }, "202": { "description": "Export still in progress." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "410": { "description": "Export expired or cancelled." } } }, "delete": { "tags": [ "FHIR" ], "summary": "Bulk Data Access — cancel export job", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Cancellation accepted." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/ask": { "get": { "tags": [ "Ask" ], "summary": "Structured, cited answer over the resolved graph (ask/v1)", "description": "Deterministic question-answering: a typed question and identifier in, a cited answer out. Available provenance fields identify the source and date; fields can be null and are not individually signed. No language model is in the retrieval path. For the sanctions question, an empty answer is returned only when the internal OIG coverage guard reports reconciled `current`; that state is not a same-day upstream-freshness claim. Stale or indeterminate coverage returns 503 and is not a clearance. A 400 returns the endpoint's self-documenting question catalog.", "parameters": [ { "in": "query", "name": "question", "required": true, "schema": { "type": "string", "enum": [ "ownership", "sanctions", "payments" ] }, "description": "`ownership` (1-hop entity-graph edges), `sanctions` (OIG LEIE exclusions by NPI), `payments` (CMS Open Payments by recipient NPI or teaching-hospital CCN)." }, { "in": "query", "name": "scheme", "required": true, "schema": { "type": "string", "example": "npi" }, "description": "Identifier scheme accepted by the question (e.g. `npi`, `ccn`). The 400 catalog lists accepted schemes per question." }, { "in": "query", "name": "value", "required": true, "schema": { "type": "string", "example": "1003000118" }, "description": "Identifier value; normalized per scheme." } ], "responses": { "200": { "description": "Cited answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAnswer" } } } }, "400": { "description": "Unknown question / scheme not accepted / value fails normalization. Body carries the question catalog." }, "502": { "description": "Source read failed — refuses to answer from a partial record." }, "503": { "description": "OIG sanctions coverage is stale or indeterminate. The response carries determination, coverage status, and serving/attestation evidence; no negative determination was made.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskAnswer" } } } } } } }, "/api/v1/entity/resolve": { "get": { "tags": [ "Entity Graph" ], "summary": "Resolve an identifier to its graph entity", "description": "Resolve any registered identifier (npi, ccn, ccn_asc, pecos_enrlmt_id, pac_id, and more) to its entity-graph node. A 400 lists the authoritative `valid_schemes`.", "parameters": [ { "in": "query", "name": "scheme", "required": true, "schema": { "type": "string", "example": "npi" }, "description": "Identifier scheme. See the 400 `valid_schemes` for the authoritative list." }, { "in": "query", "name": "value", "required": true, "schema": { "type": "string", "example": "1003000118" }, "description": "Identifier value; normalized per scheme." } ], "responses": { "200": { "description": "Resolution result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResolution" } } } }, "400": { "description": "Unknown/missing scheme or value fails the scheme normalization guard." }, "404": { "description": "Identifier not present in the resolved graph." } } } }, "/api/v1/entity/{entity_id}": { "get": { "tags": [ "Entity Graph" ], "summary": "Read an entity node (identifiers + 1-hop edges)", "parameters": [ { "in": "path", "name": "entity_id", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Entity-graph node id (UUID)." } ], "responses": { "200": { "description": "Entity with cross-source identifiers and 1-hop edges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNode" } } } }, "400": { "description": "Malformed entity id." }, "404": { "description": "Entity not found." } } } }, "/api/v1/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." } } } }, "/api/v1/history/{subject_type}/{subject_id}": { "get": { "tags": [ "History" ], "summary": "Retained provenance claims at a captured coordinate", "description": "Return retained claims matching a valid-time and/or transaction-time coordinate under `bitemporal-read/v1`. Most claims have no superseded version, so a requested historical coordinate may be empty; this is not universal record replay.", "parameters": [ { "in": "path", "name": "subject_type", "required": true, "schema": { "type": "string", "example": "npi" }, "description": "Subject type (e.g. `npi`, `ccn`)." }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" }, "description": "Subject identifier value." }, { "in": "query", "name": "at", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Valid-time instant (default: now)." }, { "in": "query", "name": "recorded_at", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Transaction-time ceiling (default: now)." } ], "responses": { "200": { "description": "Claims retained at the requested coordinate; the response may contain no prior version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistorySnapshot" } } } }, "400": { "description": "Invalid subject or timestamp." }, "503": { "description": "history_index_pending — point-in-time index still building." } } } }, "/api/v1/history/{subject_type}/{subject_id}/diff": { "get": { "tags": [ "History" ], "summary": "Record diff between two instants (added / removed / changed)", "parameters": [ { "in": "path", "name": "subject_type", "required": true, "schema": { "type": "string", "example": "npi" } }, { "in": "path", "name": "subject_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Earlier instant." }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Later instant." }, { "in": "query", "name": "recorded_at", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Knowledge state for both snapshots." } ], "responses": { "200": { "description": "Field-level diff between the two reconstructed snapshots.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing/invalid from or to." }, "503": { "description": "history_index_pending." } } } }, "/api/export": { "get": { "tags": [ "Export" ], "summary": "RAG export of cataloged studies, datasets, and key pages", "description": "Structured export of the studies, datasets, and key pages registered in this export surface. Items include a stable URL and the source, methodology, or provenance links available in their catalog entry; inclusion is not universal site coverage. No authentication required.", "security": [], "parameters": [ { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" }, "description": "Output format." }, { "in": "query", "name": "type", "required": false, "schema": { "type": "string", "enum": [ "studies", "datasets", "pages", "all" ], "default": "all" }, "description": "Subset to export." } ], "responses": { "200": { "description": "Export envelope (JSON) or concatenated markdown.", "content": { "application/json": { "schema": { "type": "object", "properties": { "export_version": { "type": "string" }, "discovery_url": { "type": "string", "format": "uri" }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object" } } } } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/api/v1/platform-stats": { "get": { "tags": [ "Platform truth" ], "summary": "Read the latest dated platform-coverage observation", "description": "Returns the latest stored platform observation. The observation date is not an upstream refresh date; each source follows its own release and loaded-data cadence.", "security": [], "responses": { "200": { "description": "Dated platform metrics and their source labels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformStatsObservation" } } } } } } }, "/api/v1/rag/chunks": { "get": { "tags": [ "Export" ], "summary": "Paginated, citation-ready RAG chunk export (rag-chunks/v1)", "description": "Deterministic, paginated feed of citation-ready text chunks for entries included in the registered RAG corpus. No language model runs in the export pipeline. Emitted chunks carry the provenance fields available to that corpus entry plus a stable citation string; fields can be null, and corpus coverage is narrower than the complete source registry. Protected by the shared API-key minute/day quota; the read-only sample uses an additional trusted-client shard. Complements the page-level `/api/export`.", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Chunks per page; oversized values clamp to the ceiling." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Opaque start index; pass back the response's `next_cursor`." } ], "responses": { "200": { "description": "A page of provenance-carrying chunks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RagChunkPage" } } } }, "400": { "description": "limit / cursor failed validation (non-numeric or negative)." }, "429": { "description": "API-key quota exceeded; Retry-After set." }, "500": { "description": "A chunk failed the export contract gate and was not served." } } } }, "/api/v1/health": { "get": { "tags": [ "Health" ], "summary": "Service health + available source timing", "description": "Public endpoint. Returns service health and the source-timing records included by the endpoint; it is not a complete or upstream-freshness ledger for every active source.", "security": [], "responses": { "200": { "description": "Healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "uptime_target": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } } } } }, "/api/v1/status": { "get": { "tags": [ "Health" ], "summary": "Available source-status + integrity signals", "description": "Public endpoint (moat-defense #125). For source families represented in the response, reports configured timing targets, stored successful-run or snapshot observations where available, computed status, and available integrity signals such as schema drift or quarantined ingests. These fields do not establish upstream freshness for omitted sources. `summary.overall` summarizes the records the endpoint could read; each table read degrades independently and the endpoint returns 200 with partial or unknown data when necessary.", "security": [], "responses": { "200": { "description": "Source-status report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "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", "properties": { "overall": { "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": { "type": "array", "items": { "type": "object" } } } }, "provenance": { "type": "object" }, "meta": { "type": "object" } } } } } } } } }, "/api/v1/chain/manifest": { "get": { "tags": [ "Integrity" ], "summary": "Download the complete snapshot-attestation manifest", "description": "Public, no-store manifest for independently reproducing every stored snapshot commitment. Reads are fully paginated and joined to source_snapshots for row_count. The endpoint fails closed with 503 instead of returning a partial manifest when any integrity-evidence read or join is incomplete. For count-observation-v1 entries, content_size_bytes is null and the historical row count that occupied the legacy size field is disclosed separately.", "security": [], "responses": { "200": { "description": "Complete snapshot-attestation manifest, newest attestation first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "bootstrapped", "complete", "public_key", "public_key_id", "public_key_url", "chain_url", "verify_url", "total_links", "latest_hash", "latest_snapshot", "returned", "snapshots" ], "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", "null" ] }, "public_key_id": { "type": [ "string", "null" ] }, "public_key_url": { "type": "string", "format": "uri" }, "chain_url": { "type": "string", "format": "uri" }, "verify_url": { "type": "string", "format": "uri" }, "total_links": { "type": [ "integer", "null" ], "minimum": 0 }, "latest_hash": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "latest_snapshot": { "type": [ "object", "null" ], "required": [ "timestamp", "dataset", "rows", "content_hash", "hash_version" ], "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" } } }, "returned": { "type": "integer", "minimum": 0 }, "snapshots": { "type": "array", "items": { "type": "object", "required": [ "attestation_id", "snapshot_id", "source_id", "snapshot_date", "content_hash", "digest", "hash_algorithm", "hash_version", "row_count", "content_size_bytes", "legacy_content_size_field_value", "content_size_limitation", "signed_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}$" }, "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Compatibility alias of content_hash." }, "hash_algorithm": { "type": "string", "enum": [ "SHA-256" ] }, "hash_version": { "type": "string", "description": "Commitment construction, such as count-observation-v1, raw-file-sha256-v1, or fonteum-row-merkle-jcs-v1." }, "row_count": { "type": "integer", "minimum": 0 }, "content_size_bytes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Canonical rowset byte size for row-level commitments; null for count-observation-v1 because its historical field value was not a byte measurement." }, "legacy_content_size_field_value": { "type": [ "integer", "null" ], "minimum": 0, "description": "Historical value stored in content_size_bytes for count-observation-v1; this value is a row count, not bytes." }, "content_size_limitation": { "type": [ "string", "null" ], "description": "Plain-language disclosure for count-observation-v1 entries whose legacy size field contained a row count rather than bytes." }, "signed_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" } } } } } } } } }, "/api/v1/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", "null" ] } } } } } }, "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", "null" ], "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." } } } }, "/api/v1/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" } } } } } } }, "/api/v1/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" } } } } } } }, "/api/v1/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" } } } } } } } } }, "/api/v1/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" } } } } } } }, "/api/v1/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 routes to contact. 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" } } } } } } }, "/api/v1/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", "null" ] }, "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." } } } }, "/api/v1/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" } } } }, "/api/v1/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" } } } }, "/api/v1/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" } } } }, "/api/v1/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" } } } }, "/api/v1/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" } } } }, "/api/v1/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", "null" ], "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", "null" ] }, "compromised_anywhere": { "type": [ "boolean", "null" ] }, "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" } } } }, "/api/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" } } } } } } }, "/api/v1/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", "null" ], "format": "date-time" } } } } } }, "400": { "description": "CCN format is invalid." }, "404": { "description": "No canonical crosswalk link is available for this CCN." } } } }, "/api/v1/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. It does not return facility-level Care Compare ratings.", "security": [], "responses": { "200": { "description": "Data-quality scorecard.", "content": { "application/json": { "schema": { "type": "object", "required": [ "generated_at", "composite_score", "completeness", "consistency", "timeliness", "oig_leie_match_rate", "_methodology" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "composite_score": { "type": "number", "minimum": 0, "maximum": 1 }, "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" } } } } } } } } }, "/api/v1/mcp/search-records": { "get": { "tags": [ "Search" ], "operationId": "searchHostedMcpRecords", "summary": "Search records with the hosted MCP schema", "description": "REST bridge for the released `fonteum_search_records` MCP tool and @fonteum/mcp package. Requires a healthcare vertical and state; it returns the same source-and-capture-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" ], "properties": { "data": { "type": "object" }, "provenance": { "type": "object" } } } } } }, "400": { "description": "Missing or invalid hosted MCP search input." }, "401": { "description": "Missing or invalid Fonteum API key." } } } }, "/api/v1/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_dataset_info` MCP tool and @fonteum/mcp package. Returns the current methodology, source and capture 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" ], "properties": { "data": { "type": "object", "properties": { "methodology_version": { "type": "string" }, "methodology_url": { "type": "string", "format": "uri" }, "platform_coverage": { "type": [ "object", "null" ], "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" } } } } } }, "401": { "description": "Missing or invalid Fonteum API key." } } } }, "/api/v1/mcp/recheck": { "get": { "tags": [ "Methodology" ], "operationId": "getHostedMcpRecheck", "summary": "Re-check a record with the hosted MCP schema", "description": "REST bridge for the released `fonteum_recheck` MCP tool and @fonteum/mcp package. Returns the hosted re-check envelope, including available source links, signed fingerprint context, and snapshot details; it is not the narrower attestation-verifier 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" ], "properties": { "data": { "type": "object" }, "provenance": { "type": "object" } } } } } }, "400": { "description": "snapshot_id is not a positive integer." }, "401": { "description": "Missing or invalid Fonteum API key." } } } }, "/api/v1/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" } } } }, "/api/v1/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", "null" ], "allOf": [ { "$ref": "#/components/schemas/PlatformCoverage" } ] }, "active_source_family_count": { "type": [ "integer", "null" ], "minimum": 0, "deprecated": true, "description": "Deprecated v1 alias of platform_coverage.sources_integrated. Null when the dated platform snapshot is unavailable." }, "active_source_family_count_as_of": { "type": [ "string", "null" ], "format": "date", "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" } } } } } } } } }, "/api/v1/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", "null" ], "allOf": [ { "$ref": "#/components/schemas/PlatformCoverage" } ] }, "active_source_family_count": { "type": [ "integer", "null" ], "minimum": 0, "deprecated": true, "description": "Deprecated v1 alias of platform_coverage.sources_integrated. Null when the dated platform snapshot is unavailable." }, "active_source_family_count_as_of": { "type": [ "string", "null" ], "format": "date", "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" } } } } } } } } } } } }, "/api/v1/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" } } } } } } }, "/api/v1/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", "null" ], "properties": { "summary": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "unit": { "type": [ "string", "null" ] }, "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", "null" ], "format": "uri" }, "last_checked": { "type": "string", "format": "date-time" }, "confidence": { "type": "number" } } }, "methodology": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } } } } }, "refusal": { "type": [ "object", "null" ], "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" } } } }, "/api/v1/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`, `X-Total-Chunks`, and `X-Narrative-Cache-Hit`.", "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", "null" ] }, "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" } } } }, "/api/v1/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" } } } }, "/api/v1/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" } } } } } }