{ "openapi": "3.0.3", "info": { "title": "Fonteum API", "version": "1.0.0", "description": "Fonteum — the source-lineage layer for provider data. Programmatic access to source-provenanced provider supply data. Every response carries per-field provenance metadata: source URL, last-checked timestamp, confidence score (where applicable), and methodology link. Audit-grade trust is the architecture, not a feature.\n\nAccess is operator-approved during the pilot. Request a key at https://fonteum.com/data-platform/api-access.", "x-product-name": "Fonteum", "contact": { "name": "Fonteum API", "email": "api@fonteum.com", "url": "https://fonteum.com/data-platform" }, "license": { "name": "Fonteum Editorial Policy", "url": "https://fonteum.com/editorial-policy" } }, "servers": [ { "url": "https://fonteum.com/api/v1", "description": "Production v1" } ], "tags": [ { "name": "Health", "description": "Service health and per-source freshness." }, { "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": "Audit Pack", "description": "Per-dataset compliance artifact (§194). Versioned methodology, per-field provenance map, reproducibility, limitations, change history, downloadable PDF + JSON." }, { "name": "Evidence Query", "description": "Provenance-grounded natural-language Q&A (§197). Ask questions about provider supply; get the answer plus a per-claim evidence trail (source URL, last-checked, methodology version, confidence). The LLM-classifier output is runtime-validated against a strict whitelist enum and never produces SQL — typed dispatchers handle the data lookup." }, { "name": "Exports", "description": "AI-native LLM-ready exports (§198). Pre-chunked text representations of each dataset with inline methodology, source provenance, and citation per chunk. Three formats: NDJSON (streaming), JSON (RAG-ready envelope), text-blocks (paste-into-LLM-prompt-ready). Buyers run their own embedding model + vector store; we provide grounding-ready text + citations." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (`ownl_`)", "description": "Pass your operator-issued API key as `Authorization: Bearer ownl_...`. Request access via https://fonteum.com/data-platform/api-access." } }, "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", "format": "date-time", "nullable": true }, "cadence": { "type": "string" } } }, "ResponseMeta": { "type": "object", "required": [ "request_id", "api_version", "data_freshness", "methodology_url", "limitations_url" ], "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" } } } } }, "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/dermatology-provider-supply-by-state-2026" }, "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" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "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": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Service health + per-source freshness", "description": "Public endpoint. Reports last successful refresh per source family.", "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" } } } } } } } } }, "/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" } } } } } } }, "/specialties": { "get": { "tags": [ "Specialties" ], "summary": "List all available specialties", "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" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/specialties/{code}/by-state": { "get": { "tags": [ "Specialties" ], "summary": "Per-state density for one specialty", "description": "Returns 51 rows (50 states + DC) with per-field provenance.\n\n**Optional `subspecialty` filter (§193).** When supplied, the response is recomputed against NPPES providers whose `taxonomy_codes` array includes the requested NUCC code. Counts, `per_100k`, `rank_density`, and `quartile` are recomputed from the filtered slice. The parent study's underserved threshold doesn't transfer, so filtered rows always carry `underserved: false`.\n\nSupported `subspecialty` codes per primary specialty (built from §183 / §188 specialty-study configs — same taxonomies the underlying ingest scoped to):\n\n- **cardiology**: single-taxonomy ingest (`207RC0000X` — Internal Medicine, Cardiovascular Disease (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **dermatology** (5 taxonomies):\n - `207N00000X` — Dermatology (parent)\n - `207ND0900X` — Dermatopathology\n - `207NI0002X` — Clinical & Laboratory Dermatological Immunology\n - `207NP0225X` — Pediatric Dermatology\n - `207NS0135X` — Procedural Dermatology / MOHS\n- **gastroenterology**: single-taxonomy ingest (`207RG0100X` — Internal Medicine, Gastroenterology). `?subspecialty=` either matches the parent or returns zero rows.\n- **neurology**: single-taxonomy ingest (`2084N0400X` — Psychiatry & Neurology, Neurology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **obgyn** (3 taxonomies):\n - `207V00000X` — Obstetrics & Gynecology (parent)\n - `207VX0000X` — Obstetrics & Gynecology, Obstetrics\n - `207VG0400X` — Obstetrics & Gynecology, Gynecology\n- **oncology**: single-taxonomy ingest (`207RX0202X` — Internal Medicine, Medical Oncology). `?subspecialty=` either matches the parent or returns zero rows.\n- **ophthalmology**: single-taxonomy ingest (`207W00000X` — Ophthalmology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **orthopedic**: single-taxonomy ingest (`207X00000X` — Orthopaedic Surgery (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **otolaryngology**: single-taxonomy ingest (`207Y00000X` — Otolaryngology (parent)). `?subspecialty=` either matches the parent or returns zero rows.\n- **pediatrics** (20 taxonomies):\n - `208000000X` — Pediatrics (parent)\n - `2080A0000X` — Pediatrics, Adolescent Medicine\n - `2080P0006X` — Pediatrics, Developmental — Behavioral Pediatrics\n - `2080P0008X` — Pediatrics, Neurodevelopmental Disabilities\n - `2080N0001X` — Pediatrics, Neonatal-Perinatal Medicine\n - `2080P0202X` — Pediatrics, Pediatric Cardiology\n - `2080P0203X` — Pediatrics, Child Abuse Pediatrics\n - `2080P0204X` — Pediatrics, Pediatric Emergency Medicine\n - `2080P0205X` — Pediatrics, Pediatric Hematology-Oncology\n - `2080P0206X` — Pediatrics, Pediatric Endocrinology\n - `2080P0207X` — Pediatrics, Pediatric Hematology-Oncology (alt)\n - `2080P0208X` — Pediatrics, Pediatric Infectious Diseases\n - `2080P0210X` — Pediatrics, Pediatric Pulmonology\n - `2080P0214X` — Pediatrics, Pediatric Rheumatology\n - `2080P0216X` — Pediatrics, Pediatric Sports Medicine\n - `2080I0007X` — Pediatrics, Pediatric Infectious Diseases (alt)\n - `2080S0010X` — Pediatrics, Sleep Medicine\n - `2080S0012X` — Pediatrics, Sports Medicine\n - `2080T0002X` — Pediatrics, Pediatric Transplant Hepatology\n - `2080H0002X` — Pediatrics, Hospice and Palliative Medicine\n- **psychiatry**: single-taxonomy ingest (`2084P0800X` — Psychiatry (individual provider)). `?subspecialty=` either matches the parent or returns zero rows.\n- **urology**: single-taxonomy ingest (`208800000X` — Urology (parent)). `?subspecialty=` either matches the parent or returns zero rows.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string", "example": "dermatology" } }, { "in": "query", "name": "subspecialty", "required": false, "description": "NUCC taxonomy code to filter on. Must be registered for the primary specialty (see endpoint description). Example: `207NS0135X` (Procedural Dermatology / MOHS) for primary `dermatology`.", "schema": { "type": "string", "example": "207NS0135X" } } ], "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/specialties/{code}/by-county": { "get": { "tags": [ "Specialties" ], "summary": "Per-county aggregate (state-level density proxy)", "description": "NPPES does not publish a county-level field of practice in its public API. Responses surface the parent state's density figure with the county context preserved in `meta.geo_scope_note`. Mirrors the §191 Access Gap Lookup Tool's honesty disclosure.\n\n**Optional `subspecialty` filter (§193).** Same semantics as `/specialties/{code}/by-state` — the recomputed slice is intersected with the requested state, and the resulting state-level row is returned in `data.state_level_supply`.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string", "example": "CA" } }, { "in": "query", "name": "county_fips", "required": true, "schema": { "type": "string", "example": "06037" } }, { "in": "query", "name": "subspecialty", "required": false, "description": "NUCC taxonomy code to filter on. See `/specialties/{code}/by-state` description for the per-primary registry.", "schema": { "type": "string", "example": "207NS0135X" } } ], "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" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/states/{state}/coverage": { "get": { "tags": [ "States" ], "summary": "Combined per-specialty coverage for one state", "parameters": [ { "in": "path", "name": "state", "required": true, "schema": { "type": "string", "example": "CA" } } ], "responses": { "200": { "description": "Per-specialty rollup.", "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" } } } }, "/providers/{npi}": { "get": { "tags": [ "Providers" ], "summary": "Single provider lookup by NPI", "parameters": [ { "in": "path", "name": "npi", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" } } ], "responses": { "200": { "description": "Provider record with per-field provenance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProviderRecord" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/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" } } } }, "/evidence-query": { "post": { "tags": [ "Evidence Query" ], "summary": "Provenance-grounded natural-language Q&A (§197)", "description": "POST a natural-language question about U.S. healthcare-provider supply data. Returns a 1-2 sentence answer plus a per-claim evidence trail (source URL, last-checked timestamp, methodology version + URL, confidence score, per-claim limitations).\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. Per-claim provenance is attached from the audit-pack registry; a second LLM call writes the summary constrained to the resolver's exact numbers, with a deterministic-template fallback.\n\n**County-scope honesty:** NPPES has no public county-of-practice field. Queries scoped to a county return state-level supply with `geo_widened: true` flagged in the answer and an explicit limitation in the evidence trail.\n\n**Refusal codes:** `out_of_scope`, `predictions`, `payment_data`, `competitor_compare`, `individual_provider_lookup`, `prompt_injection`, `classification_failed`. Refusals return HTTP 200 with `status: \"refusal\"` and a machine-readable `refusal.code`.\n\nDemo (no auth, 10 queries / 24h per IP): POST `/api/evidence-query/demo` with the same body shape.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1500, "example": "How many active dermatologists practice in Texas, and how is that number sourced?" }, "options": { "type": "object", "properties": { "max_evidence_items": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } } } } } } }, "responses": { "200": { "description": "Answer + evidence trail (or refusal).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "refusal" ] }, "answer": { "type": "object", "nullable": true, "properties": { "summary": { "type": "string" }, "value": { "type": "number", "nullable": true }, "unit": { "type": "string", "nullable": true }, "dataset": { "type": "string" }, "dataset_slug": { "type": "string" }, "methodology_version": { "type": "string", "example": "v2026.05.0" }, "geo_widened": { "type": "boolean" } } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "claim": { "type": "string" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "tier": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "url": { "type": "string", "format": "uri", "nullable": true }, "last_checked": { "type": "string", "format": "date-time" }, "confidence": { "type": "number" } } }, "methodology": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } } } } }, "refusal": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "400": { "description": "Malformed request (invalid JSON, missing query, or query too long)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{dataset}/llm-ready": { "get": { "tags": [ "Exports" ], "summary": "AI-native LLM-ready export for a dataset (§198)", "description": "Returns the named dataset as pre-chunked text + structured fields + inline methodology + APA citation, in one of three formats:\n\n- `?format=json` (default) — single-document RAG envelope with `dataset`, `narrative`, `chunks[]`, `meta`. Best for batch ingestion where the buyer reads the full payload, indexes the chunks array into a vector DB.\n- `?format=ndjson` — newline-delimited JSON. The first line is a `_dataset_meta` header; subsequent lines are individual chunks. Streaming-friendly; pipe directly into an embedding worker without buffering the full document.\n- `?format=text-blocks` — plain text with `--- METHODOLOGY ---` / `--- CHUNK ---` / `--- CITATION FOOTER ---` delimiters. Designed for direct paste into an LLM prompt for grounded retrieval-free generation.\n\n**Per-chunk shape** (all formats):\n- `id` — stable identifier (e.g. `dermatology-supply:state:CA:v2026.05.0`)\n- `text` — LLM-ready paragraph with provenance baked in\n- `data` — structured fields mirror of the text (state_code, count, density_per_100k, rank, etc.)\n- `methodology` — inline `version`, `source`, `source_url`, `last_checked`, `cadence`, `limitations[]`\n- `citation` — APA-style citation\n- `chunk_type` — `national` | `state` | `underserved` | `dataset_meta`\n\n**Narrative** — a 1-2 paragraph synthetic summary of the dataset, generated via Claude Sonnet on first request and cached per (dataset_slug, methodology_version). Cache hits are free; misses pay the LLM call once per methodology version. Returned as `narrative` in the JSON envelope, in the NDJSON header line, and as a `--- NARRATIVE ---` block in text-blocks.\n\n**Embedding intentionally omitted** — buyers run their own embedding model (OpenAI / Voyage / Cohere) and own their vector storage. This endpoint provides only the grounding-ready text + citations.\n\n**Response headers:** `X-Methodology-Version`, `X-Last-Refreshed`, `X-Total-Chunks`, `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", "nullable": true }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "data": { "type": "object" }, "methodology": { "type": "object", "properties": { "version": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "last_checked": { "type": "string", "format": "date-time" }, "cadence": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "citation": { "type": "string" }, "chunk_type": { "type": "string", "enum": [ "national", "state", "underserved", "dataset_meta" ] } } } }, "meta": { "type": "object" } } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "One JSON object per line. First line is `_line_type: dataset_meta`; subsequent lines are `_line_type: chunk` with the same per-chunk shape as the JSON format." } }, "text/plain": { "schema": { "type": "string", "description": "Plain text with delimited blocks: `--- METHODOLOGY ---` header, optional `--- NARRATIVE ---`, then `--- CHUNK ---` blocks, ending with `--- CITATION FOOTER ---`." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audit-pack": { "get": { "tags": [ "Audit Pack" ], "summary": "List all available Audit Packs (§194)", "description": "Returns a catalog of all 16 Audit Packs (12 NPPES specialty supply studies + 4 CMS Care Compare facility studies). Each entry includes the dataset slug, current methodology version, refresh cadence, and direct links to the public web view, the PDF download, and the JSON download. Compliance-tool integrations consume this endpoint to keep their internal Audit Pack catalog in sync.", "responses": { "200": { "description": "Catalog list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audit-pack/{slug}": { "get": { "tags": [ "Audit Pack" ], "summary": "Authenticated Audit Pack metadata + per-field provenance map (§194)", "description": "Returns the full Audit Pack JSON envelope (schema_version 1.0) for a single dataset — methodology version, per-field provenance map, reproducibility steps, limitations stack, version history, compliance Q&A. The same shape is downloadable publicly without auth at GET /api/audit-pack/{slug}/json (and as a PDF at GET /api/audit-pack/{slug}/pdf); this v1 endpoint is for compliance-tool integrations that already auth against the API.", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "example": "dermatology-supply" } } ], "responses": { "200": { "description": "Audit Pack envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }