# CCA Medical Providers API

> Read-only mirror of national health care provider registries. Search, look up,
> and resolve providers from bulk registry publications. Every read is served
> from the local mirror; no upstream registry is called on the request path.

Base URL: https://medicalproviders.datasourceapi.com
API root: https://medicalproviders.datasourceapi.com/api/v1

## What this is

A registry-neutral provider directory. The data model uses jurisdiction-neutral
field names (`subdivision`, `postalCode`, `localId`) so one representation
describes any national registry. The US CMS NPPES corpus is the first registry;
others are added as adapters without changing the API.

## Coverage

- `us-nppes`: 29,158 provider records

## Freshness

- `us-nppes/full`: unknown
- `us-nppes/weekly`: current (release 2026-09-07..2026-09-13)

## Contracts

- [OpenAPI 3.1 (JSON)](https://medicalproviders.datasourceapi.com/openapi.json)
- [OpenAPI 3.1 (YAML)](https://medicalproviders.datasourceapi.com/openapi.yaml)
- [RFC 9727 API catalog](https://medicalproviders.datasourceapi.com/.well-known/api-catalog)
- [APIs.json](https://medicalproviders.datasourceapi.com/apis.json)
- [Arazzo workflows](https://medicalproviders.datasourceapi.com/arazzo.yaml)
- [OpenAPI overlay](https://medicalproviders.datasourceapi.com/agent-enrichment.overlay.yaml)
- [Markdown documentation](https://medicalproviders.datasourceapi.com/docs.md)

## Operations

- `GET /api/v1/health` — Check process liveness.
- `GET /api/v1/ready` — Check request-serving readiness.
- `GET /api/v1/status` — Get coverage, freshness, pipeline state, and shard capacity.
- `GET /api/v1/capacity` — Get D1 shard capacity telemetry.
- `GET /api/v1/sources` — List upstream sources with provenance and use constraints.
- `GET /api/v1/registries` — List supported and planned national provider registries.
- `GET /api/v1/registries/{registry}` — Get one registry with its datasets and coverage.
- `GET /api/v1/providers` — Search providers by name, place, or classification.
- `GET /api/v1/registries/{registry}/providers/{localId}` — Get one provider by its registry-issued identifier.
- `GET /api/v1/providers/{providerId}` — Get one provider by its stable fleet identifier.
- `GET /api/v1/providers/{providerId}/changes` — Get the field-level change log for one provider.
- `GET /api/v1/registries/{registry}/providers/{localId}/changes` — Get the field-level change log by registry identifier.
- `GET /api/v1/resolve/{system}/{value}` — Resolve an external identifier to a provider.
- `GET /api/v1/taxonomies` — List available provider classification code sets.
- `GET /api/v1/taxonomies/{system}` — Browse or search a classification code set.
- `GET /api/v1/taxonomies/{system}/{code}` — Resolve one classification code.
- `GET /api/v1/releases` — List promoted data releases.
- `GET /api/v1/releases/{registry}/{dataset}/{releaseCode}` — Get one release with its provenance manifest reference.

Every operation above carries a stable `operationId` in the OpenAPI document,
a documented 2xx response schema, and at least one documented error response.

## Response shape

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 are RFC 9457 problem documents that also carry the envelope members, so
`type`, `title`, `status`, `detail`, `instance`, `request_status`, and
`error_code` are all present on the same body.

## Pagination

Opaque keyset cursors. Read `data.pagination.next_cursor` and pass it back as
`cursor`. Offset pagination is not supported and is rejected rather than ignored.

## Things an agent must not claim

- Registration in a provider registry does **not** mean a provider is licensed or credentialed.
  Licence numbers are self-reported to the registry and are not verified here.
- Deactivated records are redacted at source. A record with no name and no
  address is a real, withdrawn registration, not missing data.
- NPPES data is published on the condition that it is not used to solicit the
  listed providers. `meta.sources[].solicitationRestricted` carries this flag.
- Use constraints published by this API are descriptive metadata, not legal
  determinations.

## Planned registries

- `ca-cihi` (CA): Canadian health care provider registries — not implemented, carries no data
- `gb-nhs-ods` (GB): NHS Organisation Data Service — not implemented, carries no data
- `au-ahpra` (AU): Australian Health Practitioner Regulation Agency register — not implemented, carries no data

## Status

- [Service status](https://medicalproviders.datasourceapi.com/api/v1/status)
- [Source provenance](https://medicalproviders.datasourceapi.com/api/v1/sources)
- [Shard capacity](https://medicalproviders.datasourceapi.com/api/v1/capacity)