# CCA Medical Providers API

Version 1.0.0 · Base URL `https://medicalproviders.datasourceapi.com`

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](https://medicalproviders.datasourceapi.com/openapi.json)
- [Service status](https://medicalproviders.datasourceapi.com/api/v1/status)
- [Source provenance](https://medicalproviders.datasourceapi.com/api/v1/sources)
- [RFC 9727 catalog](https://medicalproviders.datasourceapi.com/.well-known/api-catalog)
- [Agent entry point](https://medicalproviders.datasourceapi.com/llms.txt)

## Registries

- **`us-nppes`** — US National Plan and Provider Enumeration System (US). Identifier: National Provider Identifier (NPI). Cadence: Monthly full replacement published around the middle of the month, weekly increments published each Monday, and a monthly deactivation report.

Planned, carrying no data: `ca-cihi`, `gb-nhs-ods`, `au-ahpra`.

## Conventions

**Envelope.** `{ request_status, message, data, meta }`. `meta.sources` lists only
the sources that contributed to that response.

**Errors.** RFC 9457 problem documents that also carry the envelope members.
Request `application/problem+json` to receive that media type; the body is the
same either way.

**Pagination.** Opaque keyset cursors via `data.pagination.next_cursor`. Offset
pagination is rejected rather than ignored.

**Caching.** Every cacheable GET publishes `Cache-Control` and a strong `ETag`,
and honours `If-None-Match`.

**Identifiers.** `providerId` matches `^source-[0-9a-z]{12}$` and is derived
deterministically from the registry and its issued identifier. Validate the
syntax and otherwise treat it as opaque.

<a id="use-constraints"></a>

## 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`

**`getProviderDirectoryHealth`** — 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 https://medicalproviders.datasourceapi.com/api/v1/health
```

### `GET /api/v1/ready`

**`getProviderDirectoryReadiness`** — 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`

**`getProviderDirectoryStatus`** — 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 https://medicalproviders.datasourceapi.com/api/v1/status
```

### `GET /api/v1/capacity`

**`getProviderDirectoryCapacity`** — 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`

**`listProviderDirectorySources`** — 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.

```
GET https://medicalproviders.datasourceapi.com/api/v1/sources
```

## Registries

### `GET /api/v1/registries`

**`listProviderRegistries`** — 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 https://medicalproviders.datasourceapi.com/api/v1/registries
```

### `GET /api/v1/registries/{registry}`

**`getProviderRegistry`** — 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`

**`searchProviders`** — 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 https://medicalproviders.datasourceapi.com/api/v1/providers?taxonomy=207RC0000X&subdivision=AZ&limit=5
```

### `GET /api/v1/registries/{registry}/providers/{localId}`

**`getProviderByRegistryIdentifier`** — 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 https://medicalproviders.datasourceapi.com/api/v1/registries/us-nppes/providers/1497107718
```

### `GET /api/v1/providers/{providerId}`

**`getProviderByStableIdentifier`** — 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`

**`getProviderChangesByStableIdentifier`** — 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`

**`getProviderChangesByRegistryIdentifier`** — 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}`

**`resolveProviderIdentifier`** — 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`

**`listProviderTaxonomySystems`** — 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 https://medicalproviders.datasourceapi.com/api/v1/taxonomies
```

### `GET /api/v1/taxonomies/{system}`

**`getProviderTaxonomyCatalog`** — 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}`

**`getProviderTaxonomyCode`** — 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. |

```
GET https://medicalproviders.datasourceapi.com/api/v1/taxonomies/nucc/207RC0000X
```

## Provenance

### `GET /api/v1/releases`

**`listProviderDataReleases`** — 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 https://medicalproviders.datasourceapi.com/api/v1/releases
```

### `GET /api/v1/releases/{registry}/{dataset}/{releaseCode}`

**`getProviderDataRelease`** — 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. |