What FHIR resources does Fonteum's API expose?

Fonteum implements HL7 FHIR R4 against US Core 6.1.0, exposing 5 distinct USCDI v3 Provider resources: Practitioner (NPI and taxonomy), PractitionerRole (Medicare enrollment and specialty), Organization, Location, and HealthcareService. Each is reachable through individual resource reads and US Core search parameters, returns application/fhir+json, and carries a 14-tuple provenance tag on its meta.tag recording the originating federal source, dataset identifier, last-checked date, and methodology version. The builders behind each resource are pure functions with no direct database calls — orchestration lives in the route handlers — and each route runs on the Node.js runtime as a dynamic endpoint. The CapabilityStatement enumerating all five resources, their supported interactions, and the SMART auth profile in its security extension is served at /api/fhir/metadata, the standard discovery endpoint an integration probes first. The reference documentation is at /docs/fhir.

How does SMART Backend Services authentication work?

Fonteum supports the SMART App Launch Backend Services profile for unattended system-to-system access. The flow is a JSON Web Token (JWT) client assertion signed with RS384, exchanged at the token endpoint for a short-lived bearer access token — no interactive user login, which is what server-side ETL, scheduled jobs, and agent runtimes need. The CapabilityStatement at /api/fhir/metadata declares the supported auth flows in its security extension, so a consuming system can discover the token endpoint and scopes programmatically before exchanging credentials. The same auth profile covers both the REST resource endpoints and the asynchronous Bulk Data Access $export, so a single credential serves both individual queries and population-scale extracts. This is the auth pattern expected by integrations that follow SMART-on-FHIR conformance, including those built against CMS interoperability obligations.

How does the bulk NDJSON export work?

A $export request triggers an Inngest-backed asynchronous job queue that serializes every provider record matching the request scope as NDJSON — newline-delimited JSON, one valid FHIR R4 resource per line, grouped into one file per resource type — and returns a manifest once the job completes. Because it is asynchronous, a large extract does not block on a single synchronous HTTP request: you poll the status endpoint and collect the files when the job is ready. The export covers all 5 USCDI v3 Provider resources, each line carrying the 14-tuple provenance tag on its meta.tag, and the manifest records per-type resource counts and the export timestamp. NDJSON loads directly with pandas.read_json(lines=True), Spark's spark.read.json, DuckDB's read_json_auto, or a BigQuery NEWLINE_DELIMITED_JSON load job, with no intermediate transformation. SMART Backend Services auth secures the operation for unattended pipeline use. The reference is at /docs/bulk-export.

Does Fonteum provide an MCP server for AI agents?

Yes. Fonteum ships a Model Context Protocol (MCP) server that exposes its provider-data and exclusion-lookup tools to AI agents, so an agent can resolve a provider by NPI or run an 'excluded anywhere' check as a tool call rather than hand-rolled HTTP glue. The agent card at /.well-known/agent.json publishes the full skills inventory, which is what multi-agent frameworks — Google ADK, LangGraph, and BeeAI — parse to discover capabilities; an empty skills array would make the service invisible to those consumers, so the inventory is populated deliberately. For the two most common Python and TypeScript agent stacks, dependency-free LangChain and LlamaIndex adapters are documented at /docs/integrations, alongside the zero-glue MCP path and the plain REST tool definitions. Each tool result carries the same field-level federal provenance as the rest of the platform, so an agent's output inherits an auditable chain back to the source file.

Are there rate limits and integrity headers on the API?

Yes. Public export endpoints apply a per-IP rate limit to keep the free surface available, and CSV and dataset exports return integrity headers — an X-Fonteum-SHA256 content hash and an X-Fonteum-Methodology-Version header — so a consumer can confirm the bytes it received and the methodology version they were produced under. The FHIR REST and bulk endpoints use SMART Backend Services auth for higher-throughput, unattended access; the asynchronous $export pattern itself is the mechanism for population-scale loads, so large jobs run as background work rather than against a synchronous request limit. The current limits and header semantics for each endpoint are documented at /docs/fhir and /docs/bulk-export. For production workloads that need dedicated throughput or a custom export cadence, the pilot tier provides scoped access starting at $2,500/mo.

Is the API free, and what does the pilot tier add?

The federal data behind the API is published openly, and the FHIR R4 REST endpoints, the bulk $export, the MCP server, and the static research datasets at /research are all part of the free public surface — the doctrine is that public-source federal data should stay public. All 44 federal source families are documented at /sources with tier, refresh cadence, and redistribution posture so a developer can confirm terms before building on a signal. The scoped pilot tier, starting at $2,500/mo, adds dedicated throughput, custom exports cut to a specific provider set, and integration support — for example a recurring NDJSON delivery keyed to your application's scope with the 14-tuple provenance intact. The pilot is about scoping, delivery, and SLA, not about gating access to the underlying federal record or the standards-conformant endpoints.

FONTEUM · USE CASE · DEVELOPERS

federal source families

Federal provider data, behind standards-conformant APIs.

HL7 FHIR R4 US Core 6.1.0, async NDJSON bulk export, SMART Backend Services auth, and an MCP server for agentic workflows — with 14-tuple provenance on every response.

Read the FHIR R4 docs →

Technical stack

FHIR R4 · bulk export · MCP

5 USCDI v3 resources
FHIR R4 US Core 6.1.0
REST provider API
5 distinct USCDI v3 Provider resources — Practitioner, PractitionerRole, Organization, Location, HealthcareService — with US Core search parameters and a 14-tuple provenance tag on each resource's meta.tag. SMART Backend Services auth (JWT / RS384). The CapabilityStatement at /api/fhir/metadata is the discovery entry point. One of 44 federal source families behind it.
Documentation →
Async NDJSON $export
HL7 Bulk Data Access
Async $export
HL7 FHIR R4 Bulk Data Access ($export) — Inngest-backed async job queue, status polling, and NDJSON output per resource type. SMART Backend Services auth. Directly loadable by Spark, Pandas, DuckDB, and BigQuery for population-scale jobs.
Documentation →
MCP + agent card
MCP server
Agentic workflows
A Model Context Protocol server exposing Fonteum's provider-data and exclusion-lookup tools to AI agents, plus an agent card at /.well-known/agent.json with the full skills inventory for Google ADK, LangGraph, and BeeAI consumers. LangChain and LlamaIndex adapters are documented at /docs/integrations.
Documentation →

Built for integration, not lock-in

Standards-conformant. Provenance-tagged. Agent-ready.

FHIR R4 US Core 6.1.0 — full USCDI v3 Provider conformance

All 5 USCDI v3 Provider resources are implemented against US Core 6.1.0 — Practitioner, PractitionerRole, Organization, Location, HealthcareService — as pure builders behind Node.js route handlers, each returning application/fhir+json with US Core search parameters. The CapabilityStatement at /api/fhir/metadata enumerates them for technical review, drawing on a graph of active providers across one of 44 federal source families.

Provenance travels with every response

Each FHIR resource carries a 14-tuple provenance tag on its meta.tag — source name, dataset identifier, last-checked date, methodology version — and the same chain rides inline in the bulk NDJSON. That means a downstream system or notebook can cite the exact federal file a record came from without reconciling separate documentation. CSV and dataset exports add X-Fonteum-SHA256 and X-Fonteum-Methodology-Version integrity headers so a consumer can confirm the bytes and the method.

Agent-native via MCP

An MCP server exposes provider-data and exclusion-lookup tools — including the “excluded anywhere” check over the OIG LEIE () and companion lists — so an agent calls a tool instead of writing HTTP glue. The agent card at /.well-known/agent.json publishes the skills inventory that Google ADK, LangGraph, and BeeAI parse, and dependency-free LangChain and LlamaIndex adapters are documented at /docs/integrations.

How it works

Discover · Authenticate · Consume

Step 1 / Discover

Discover

Probe the CapabilityStatement at /api/fhir/metadata to enumerate the 5 USCDI v3 Provider resources, their US Core search parameters, and the SMART Backend Services auth profile in the security extension. For agents, read the agent card at /.well-known/agent.json for the skills inventory. Reference docs live at /docs/fhir, /docs/bulk-export, and /docs/integrations.

Step 2 / Authenticate

Authenticate

Exchange a JWT client assertion signed with RS384 for a short-lived bearer token via SMART Backend Services — no interactive login. One credential covers the REST resource endpoints and the asynchronous bulk $export, so server-side ETL, scheduled jobs, and agent runtimes integrate the same way.

Step 3 / Consume

Consume

Query individual FHIR resources, run an async NDJSON $export for population-scale loads, or call the MCP tools from an agent. Every response carries a 14-tuple provenance tag on meta.tag, so the citation travels with the data into your system. Build on a graph of active providers — free on the public surface, with dedicated throughput available via the pilot tier.

FAQ

Common questions

What FHIR resources does Fonteum's API expose?: Fonteum implements HL7 FHIR R4 against US Core 6.1.0, exposing 5 distinct USCDI v3 Provider resources: Practitioner (NPI and taxonomy), PractitionerRole (Medicare enrollment and specialty), Organization, Location, and HealthcareService. Each is reachable through individual resource reads and US Core search parameters, returns application/fhir+json, and carries a 14-tuple provenance tag on its meta.tag recording the originating federal source, dataset identifier, last-checked date, and methodology version. The builders behind each resource are pure functions with no direct database calls — orchestration lives in the route handlers — and each route runs on the Node.js runtime as a dynamic endpoint. The CapabilityStatement enumerating all five resources, their supported interactions, and the SMART auth profile in its security extension is served at /api/fhir/metadata, the standard discovery endpoint an integration probes first. The reference documentation is at /docs/fhir. It draws on a graph of active providers.
How does SMART Backend Services authentication work?: Fonteum supports the SMART App Launch Backend Services profile for unattended system-to-system access. The flow is a JSON Web Token (JWT) client assertion signed with RS384, exchanged at the token endpoint for a short-lived bearer access token — no interactive user login, which is what server-side ETL, scheduled jobs, and agent runtimes need. The CapabilityStatement at /api/fhir/metadata declares the supported auth flows in its security extension, so a consuming system can discover the token endpoint and scopes programmatically before exchanging credentials. The same auth profile covers both the REST resource endpoints and the asynchronous Bulk Data Access $export, so a single credential serves both individual queries and population-scale extracts. This is the auth pattern expected by integrations that follow SMART-on-FHIR conformance, including those built against CMS interoperability obligations.
How does the bulk NDJSON export work?: A $export request triggers an Inngest-backed asynchronous job queue that serializes every provider record matching the request scope as NDJSON — newline-delimited JSON, one valid FHIR R4 resource per line, grouped into one file per resource type — and returns a manifest once the job completes. Because it is asynchronous, a large extract does not block on a single synchronous HTTP request: you poll the status endpoint and collect the files when the job is ready. The export covers all 5 USCDI v3 Provider resources, each line carrying the 14-tuple provenance tag on its meta.tag, and the manifest records per-type resource counts and the export timestamp. NDJSON loads directly with pandas.read_json(lines=True), Spark's spark.read.json, DuckDB's read_json_auto, or a BigQuery NEWLINE_DELIMITED_JSON load job, with no intermediate transformation. SMART Backend Services auth secures the operation for unattended pipeline use. The reference is at /docs/bulk-export.
Does Fonteum provide an MCP server for AI agents?: Yes. Fonteum ships a Model Context Protocol (MCP) server that exposes its provider-data and exclusion-lookup tools to AI agents, so an agent can resolve a provider by NPI or run an “excluded anywhere” check across the OIG LEIE ( exclusions) and companion lists as a tool call rather than hand-rolled HTTP glue. The agent card at /.well-known/agent.json publishes the full skills inventory, which is what multi-agent frameworks — Google ADK, LangGraph, and BeeAI — parse to discover capabilities; an empty skills array would make the service invisible to those consumers, so the inventory is populated deliberately. For the two most common Python and TypeScript agent stacks, dependency-free LangChain and LlamaIndex adapters are documented at /docs/integrations, alongside the zero-glue MCP path and the plain REST tool definitions. Each tool result carries the same field-level federal provenance as the rest of the platform, so an agent's output inherits an auditable chain back to the source file.
Are there rate limits and integrity headers on the API?: Yes. Public export endpoints apply a per-IP rate limit to keep the free surface available, and CSV and dataset exports return integrity headers — an X-Fonteum-SHA256 content hash and an X-Fonteum-Methodology-Version header — so a consumer can confirm the bytes it received and the methodology version they were produced under. The FHIR REST and bulk endpoints use SMART Backend Services auth for higher-throughput, unattended access; the asynchronous $export pattern itself is the mechanism for population-scale loads, so large jobs run as background work rather than against a synchronous request limit. The current limits and header semantics for each endpoint are documented at /docs/fhir and /docs/bulk-export. For production workloads that need dedicated throughput or a custom export cadence, the pilot tier provides scoped access starting at $2,500/mo.
Is the API free, and what does the pilot tier add?: The federal data behind the API is published openly, and the FHIR R4 REST endpoints, the bulk $export, the MCP server, and the static research datasets at /research are all part of the free public surface — the doctrine is that public-source federal data should stay public. All are documented at /sources with tier, refresh cadence, and redistribution posture so a developer can confirm terms before building on a signal. The scoped pilot tier, starting at $2,500/mo, adds dedicated throughput, custom exports cut to a specific provider set, and integration support — for example a recurring NDJSON delivery keyed to your application's scope with the 14-tuple provenance intact. The pilot is about scoping, delivery, and SLA, not about gating access to the underlying federal record or the standards-conformant endpoints.

Build →

Start with the technical docs.

FHIR R4 reference at /docs/fhir, bulk export at /docs/bulk-export, and agent integrations at /docs/integrations. Pilot tier from $2,500/mo.

Request access →or view the CapabilityStatement →

FONTEUM · PILOT

Run a 90-day pilot. Public data only. No PHI.

Request access → Read the methodology