API, MCP, and access
Use the public Atlas REST API, and see the current status of MCP and API keys.
Atlas publishes one public HTTP contract. Human guides on this site explain how to use it. They do not copy a second schema. The API reference is generated from the pinned public OpenAPI contract and links the raw spec. Machine-readable definitions stay on the API service.
What is available
| Surface | Status | Where it lives |
|---|---|---|
| Public REST API, version 1 | Available now | Anonymous read-only JSON at https://api.onehealthatlas.org |
| OpenAPI schema | Available now | OpenAPI schema |
| API reference | Available now | Generated API reference from that same public contract |
| Interactive reference | Available now | Swagger reference for approved public GET requests |
| Read-only reference | Available now | ReDoc reference |
| Bounded public MCP evidence tools | Available now | Anonymous read-only atlas_discover_indicators, atlas_get_county_profile, and atlas_get_evidence_provenance on the production MCP service. The public evidence tool contract owns arguments and limits. |
| MCP county identity | Available now | atlas_resolve_geographies resolves a county identity. Identity is not evidence availability, evidence adequacy, or comparability. |
| MCP operational tools | Available now | server_status and atlas_smoke_test remain registered. They report status and a smoke message. They do not read Atlas evidence. |
| User API keys in Settings | Not available | The public API does not use a key, and Settings does not create one |
The OpenAPI application version and the /v1 contract are different identifiers. Use the response fields below when you need to cite a result.
Public reads do not use an API key
The canonical public API serves current-release metadata and county observations without an API key and without a signed-in session. A request is an HTTPS GET. Collections return data, meta, and links. A single resource returns data. Errors use application/problem+json with code, HTTP status, detail, and request_id.
These routes do not select historical releases, aggregate arbitrary geographies, or return geometry. Account profile and privacy requests are separate account operations. Feedback submission accepts an optional account and still accepts a report when no account is present. Literature chat does not depend on an account session; /assistant and the legacy assistant drawer stay public and appear when that feature is enabled. The professional workspace at /app requires sign-in. Those operations sit outside this canonical public GET-read contract, so this page does not copy them as public examples.
Settings can save a default jurisdiction for a signed-in reviewer. That preference is not an API credential. See the professional workspace.
Task-oriented requests, pagination, geography, and citation are in the developer guides. Start with the quickstart.
Examples from the public contract
These requests use measure and county identifiers published for the current production release. County FIPS codes are five characters, with any leading zero preserved. case_count_floor_2023 is a privacy-protected case floor in cases, not a complete incidence count and not a diagnosis.
curl -fsS 'https://api.onehealthatlas.org/v1/indicators?page_size=10'
curl -fsS 'https://api.onehealthatlas.org/v1/measures?indicator_id=human_disease_burden&page_size=10'
curl -fsS 'https://api.onehealthatlas.org/v1/measures/case_count_floor_2023'
curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=08001&year=2023'Compare two counties by repeating geography_id. Use year or a complete start_date and end_date pair. The published county observations for this release are the annual 2023 period.
curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=08001&geography_id=08003&year=2023&page_size=1'If meta.next_page_token is present, send it back as page_token with every other query parameter unchanged. Stop when the token is null. Tokens are opaque and bound to that query and release. A changed or rejected token means you start again at the first page. A page token is not a citation.
Follow source_id and methodology_id on an observation when you need publisher, vintage, and method limitations:
curl -fsS 'https://api.onehealthatlas.org/v1/sources/human'
curl -fsS 'https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1'Read value_state with value and unit. The public states are OBSERVED, ZERO, MISSING, SUPPRESSED, UNAVAILABLE, and NO_COUNTY_LINKED_RECORD. MISSING, UNAVAILABLE, and NO_COUNTY_LINKED_RECORD are gaps. SUPPRESSED is a privacy-protected observation: the value was withheld, and the workspace shows Suppressed rather than a number. Do not replace a gap or a suppressed observation with zero. A published ZERO stays a real zero. The same rule is explained for reviewers in evidence, provenance, and uncertainty.
Limits and errors
The observation query needs one measure, geography_type=county, one or more five-digit county FIPS codes, and either year or both dates. The service rejects unsupported filters, strata, sorting, and aggregation instead of ignoring them. Problem code values include RESOURCE_NOT_FOUND, INVALID_REQUEST, UNSUPPORTED_FILTER, and UNSUPPORTED_STRATIFICATION. Keep request_id if you need support.
429 and 503 responses include Retry-After when the service supplies it. The header is a number of seconds. The public OpenAPI document does not publish a numeric quota or concurrency cap, so this guide does not state one. Wait for Retry-After, then retry the same request. Discovery collections use a short public cache. Stable detail responses may include an ETag; send If-None-Match to receive 304 when the representation is unchanged. The OpenAPI schema is the authority for parameters, status codes, and schema fields. The REST API guide explains pagination, problem codes, and version fields.
Reproduce a result
Save the request URL, measure id, county FIPS codes, period, release_id, semantic_version, methodology id and version, source id, lineage source id, dataset id, source vintage, and limitations. These routes read the current release. The same URL can change after a later release. A saved response, or a checksum of that response, is the record of what you retrieved.
A practical attribution names Atlas, the public API V1, the measure id, county FIPS, period, release id, semantic version, retrieval date, and the upstream publisher and dataset from the source resource you received. Replace every example identifier with the values in your response.
Canonical evidence for API and MCP consumers
Public REST reads return governed Atlas resources. Indicators, measures, observations, sources, and methodologies are that contract for current-release evidence. Clients are intended to use those resources rather than a schema that changes with each upstream source. The OpenAPI schema remains authoritative for HTTP fields. The generated API reference is rendered from the pinned public contract.
MCP tool definitions stay in the Atlas MCP repository and its tests. The released evidence tools return the same canonical evidence and provenance, including source identity and value state, rather than a schema that changes with each source. Sources and canonical evidence describes that design, the open-data boundary, and the clinical connections that are not released. Provenance and evidence lists the fields to keep with a value.
MCP
The MCP server is owned by the Atlas MCP repository. ADR 0003 accepts three anonymous read-only evidence tools and supersedes the historical smoke-only exposure constraint for that bounded surface. The production receipt records deployment of SHA d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9 and official-SDK discovery of exactly six tools at https://mcp.onehealthatlas.org/mcp. This guide does not re-invoke those tools.
| Tool | What the contract allows |
|---|---|
atlas_discover_indicators | Published indicators and their associated measures. Discovery states published definitions. It is not county availability. |
atlas_get_county_profile | Published observations for one exact five-digit county FIPS and one to three explicit measure-period selections. An empty selection is not a missing row, a zero, biological absence, or proof of county identity. |
atlas_get_evidence_provenance | A published source or methodology for the expected current release. It does not resolve an arbitrary observation ID or a historical release. |
atlas_resolve_geographies | County identity only, from the CDC/ATSDR SVI 2022 county source. Identity does not establish observations, evidence adequacy, or comparability, and it is not a current legal-boundary file. |
server_status, atlas_smoke_test | Operational status and a smoke message. These tools do not read Atlas evidence. |
The public evidence tool contract is authoritative for arguments, bounds, and error codes. This page does not copy those schemas. Evidence tools keep canonical API value states, units, denominators, source identity, and limitations. They do not score, diagnose, compare scientifically, write, or accept private data or a caller-supplied URL. They are not a live EHR, TEFCA, patient-level, PHI, or production clinical-laboratory connection.
The 2026-09-26 development record accepted server_status and atlas_smoke_test in server.py. That smoke-only receipt is historical. It is not the current production tool list.
REST remains the HTTP contract for the same canonical resources. OpenAPI remains authoritative for HTTP schemas. MCP does not replace that document.
API keys
Do not send an API key, bearer token, or Settings secret on the public read routes. They are not authenticated that way.
The professional workspace Settings page does not generate, show, copy, revoke, or regenerate a user API key. Planned key-management controls, including any future one-time secret display, are outside this release. Do not store a guessed credential in the browser or in a docs example.
Signed-in product features use the account session inside Atlas. That session is not a public API key and is not a substitute for the anonymous /v1 reads above.