API documentation
A read-only mirror of national health care provider registries. Every read is served from the local mirror; no upstream registry is called on the request path.
OpenAPI 3.1 (JSON) · YAML · Markdown · llms.txt · Arazzo
Conventions
Envelope
Successful responses are { request_status, message, data, meta }.
meta.sources lists only the sources that actually contributed to
that response. meta.partial is true when a shard or source could
not be consulted; a partial result is never reported as a complete zero-count result.
Errors
Errors are RFC 9457 problem documents that also carry the fleet envelope members, so
type, title,
status, detail,
instance, request_status, and
error_code are all present on the same body. Send
Accept: application/problem+json to receive that media type.
Pagination
Collections use opaque keyset cursors. Read
data.pagination.next_cursor and pass it back as
cursor. Offset pagination is rejected rather than ignored.
Caching
Every cacheable GET publishes Cache-Control and a strong
ETag, and honours If-None-Match.
HEAD is supported on every GET route.
Use constraints
US National Plan and Provider Enumeration System
- CMS publishes NPPES data under the Freedom of Information Act. Records describe named individuals and organizations and are mirrored here verbatim.
- Issuance of an NPI does not establish that a provider is licensed or credentialed. Licence numbers are self-reported to CMS and are not verified by this service.
- Deactivated records are redacted at source: CMS blanks the entity type, names, and addresses and retains only the identifier and deactivation date.
- Employer Identification Numbers and parent organization taxpayer identifiers are excluded from ingestion and are never served.
- This description is metadata, not a legal determination. Consult the upstream terms before redistributing.
Service
GET /api/v1/health
Check process liveness.
Returns the service banner and documentation links. Performs no dependency work, so it stays fast and cannot fail because a shard is slow. Use `/api/v1/ready` for request-serving readiness and `/api/v1/status` for coverage and freshness.
GET /api/v1/ready
Check request-serving readiness.
Performs one cheap control-plane read. Returns 503 when the service cannot serve requests. Does not fan out across shards.
GET /api/v1/status
Get coverage, freshness, pipeline state, and shard capacity.
Deep status. Reports per-registry record counts, per-dataset freshness against each dataset's declared staleness window, recent ingest runs, outbox depth, and the platform-reported size of every D1 shard with its threshold state and projected exhaustion.
GET /api/v1/capacity
Get D1 shard capacity telemetry.
Per-shard platform-reported size, percentage of the 10 GB per-database hard cap, recent growth rate, projected rollover and exhaustion dates, threshold state, and last verified time.
GET /api/v1/sources
List upstream sources with provenance and use constraints.
Every configured registry and dataset with its authority, cadence, last discovered and promoted release, freshness classification, last error, and the licence, redistribution, and solicitation constraints that apply to the data. The constraints are descriptive metadata, not a legal determination.
Registries
GET /api/v1/registries
List supported and planned national provider registries.
Supported registries carry data and return records. Planned registries are listed with `supported: false` and a zero record count so integrators can see intended coverage without mistaking it for available data.
GET /api/v1/registries/{registry}
Get one registry with its datasets and coverage.
Descriptor, datasets, cadence, use policy, and current record counts for a single registry.
| Parameter | In | Required | Description |
|---|---|---|---|
registry |
path | Yes | Registry code. Use `GET /api/v1/registries` for the supported list. Currently `us-nppes`. |
Providers
GET /api/v1/providers
Search providers by name, place, or classification.
Full-text search over names, places, identifiers, and taxonomy codes, with structured filters. At least one of `q`, `subdivision`, `city`, `postal_code`, or `taxonomy` is required: an unfiltered listing of the whole corpus is not served. Place filters match any address on a record, including secondary practice locations. Pagination is keyset-based; pass `data.pagination.next_cursor` back as `cursor`.
| Parameter | In | Required | Description |
|---|---|---|---|
q |
query | No | Free-text query matched against names, places, identifiers, and taxonomy codes. The final term is prefix-matched. |
registry |
query | No | Restrict to one registry. |
subdivision |
query | No | First-level subdivision code, such as a US state. |
city |
query | No | City name, matched exactly after case folding. |
postal_code |
query | No | Postal code. A five-character prefix also matches extended forms. |
taxonomy |
query | No | Taxonomy code the provider holds in any slot. |
entity_type |
query | No | Restrict to individuals or organizations. |
status |
query | No | Restrict by record lifecycle. |
include_absent |
query | No | Include records that a later full replacement no longer contained. Excluded by default. |
limit |
query | No | Maximum records to return, from 1 to 200. |
cursor |
query | No | Opaque keyset cursor from `data.pagination.next_cursor`. Offset pagination is not supported. |
GET /api/v1/registries/{registry}/providers/{localId}
Get one provider by its registry-issued identifier.
Single-shard lookup by the identifier the registry issues, such as a US National Provider Identifier. This is the cheapest read in the API and the one to prefer when the identifier is known.
| Parameter | In | Required | Description |
|---|---|---|---|
registry |
path | Yes | Registry code. Use `GET /api/v1/registries` for the supported list. Currently `us-nppes`. |
localId |
path | Yes | Identifier issued by the registry. For `us-nppes` this is the ten-digit National Provider Identifier. |
GET /api/v1/providers/{providerId}
Get one provider by its stable fleet identifier.
Lookup by the `source-` identifier. The identifier is a one-way digest of the registry and local identifier, so this read fans out across shards; prefer the registry-scoped route when the local identifier is known.
| Parameter | In | Required | Description |
|---|---|---|---|
providerId |
path | Yes | Stable fleet identifier. Opaque: validate the syntax and otherwise do not interpret it. |
GET /api/v1/providers/{providerId}/changes
Get the field-level change log for one provider.
Changes detected between promoted releases for the identity, status, place, and classification columns. The complete per-release state remains reconstructible from the immutable release manifests.
| Parameter | In | Required | Description |
|---|---|---|---|
providerId |
path | Yes | Stable fleet identifier. Opaque: validate the syntax and otherwise do not interpret it. |
limit |
query | No | Maximum records to return, from 1 to 200. |
GET /api/v1/registries/{registry}/providers/{localId}/changes
Get the field-level change log by registry identifier.
As `getProviderChangesByStableIdentifier`, keyed by the registry identifier.
| Parameter | In | Required | Description |
|---|---|---|---|
registry |
path | Yes | Registry code. Use `GET /api/v1/registries` for the supported list. Currently `us-nppes`. |
localId |
path | Yes | Identifier issued by the registry. For `us-nppes` this is the ten-digit National Provider Identifier. |
limit |
query | No | Maximum records to return, from 1 to 200. |
Resolution
GET /api/v1/resolve/{system}/{value}
Resolve an external identifier to a provider.
Resolves an identifier in a named system, such as `us-medicaid` or `us-medicare-ppin`, to the provider that carries it. The value is normalized by scheme-specific rules rather than generic separator stripping. An identifier that matches more than one provider returns 409 with every candidate listed, rather than silently choosing one.
| Parameter | In | Required | Description |
|---|---|---|---|
system |
path | Yes | Identifier system. Values published by `us-nppes` include `us-medicaid`, `us-medicare-ppin`, `us-medicare-oscar`, `us-medicare-upin`, `us-medicare-nsc`, `us-medicare-id`, and `us-other-provider-id`. |
value |
path | Yes | The identifier value as issued. |
Taxonomy
GET /api/v1/taxonomies
List available provider classification code sets.
Each code set with its version, the number of codes, whether it is served from the compiled copy or a KV override, and which registries use it.
GET /api/v1/taxonomies/{system}
Browse or search a classification code set.
Paginated catalog with an optional `q` substring filter on code, label, or classification.
| Parameter | In | Required | Description |
|---|---|---|---|
system |
path | Yes | Code set identifier. |
q |
query | No | Case-insensitive substring filter. |
limit |
query | No | Maximum records to return, from 1 to 200. |
cursor |
query | No | Opaque keyset cursor from `data.pagination.next_cursor`. Offset pagination is not supported. |
GET /api/v1/taxonomies/{system}/{code}
Resolve one classification code.
Grouping, classification, specialization, and display label for a single code.
| Parameter | In | Required | Description |
|---|---|---|---|
system |
path | Yes | Code set identifier. |
code |
path | Yes | The code to resolve. |
Provenance
GET /api/v1/releases
List promoted data releases.
Release history served from indexed metadata. The public request path never enumerates object storage to reconstruct history.
| Parameter | In | Required | Description |
|---|---|---|---|
registry |
query | No | Restrict to one registry. |
limit |
query | No | Maximum records to return, from 1 to 200. |
cursor |
query | No | Opaque keyset cursor from `data.pagination.next_cursor`. Offset pagination is not supported. |
GET /api/v1/releases/{registry}/{dataset}/{releaseCode}
Get one release with its provenance manifest reference.
Discovery evidence, archived artifacts with their declared and actual byte counts and SHA-256 digests, and the key and digest of the canonical provenance manifest that binds the release.
| Parameter | In | Required | Description |
|---|---|---|---|
registry |
path | Yes | Registry code. Use `GET /api/v1/registries` for the supported list. Currently `us-nppes`. |
dataset |
path | Yes | Dataset code within the registry. |
releaseCode |
path | Yes | Release code, URL-encoded. |