API reference

This page is generated from the public OpenAPI contract. It is not a second hand-maintained endpoint catalog. Tags, operation IDs, parameters, schemas, examples, and errors below come from that contract.

Spec version and source

Label	Value
OpenAPI version	3.1.0
Application version	0.1.0
HTTP contract	/v1
Source repository	Caraway-Labs/one-health-lyme-gap-atlas-api
Source commit	25cd3ec90a9b330c620f02ca012576fd98b3f4ab
Source file	openapi.json
Checksum	fe4f00e60af337f1b99e6293dc973c290541881d4845355fc80e20b57fcb1fa0

Application version 0.1.0 identifies the OpenAPI info.version field. The HTTP contract is /v1. Those identifiers are different. This reference build is identified by the source commit and checksum.

Raw spec: OpenAPI schema.

Pinned source: Caraway-Labs/one-health-lyme-gap-atlas-api@25cd3ec90a9b330c620f02ca012576fd98b3f4ab.

Servers

• https://api.onehealthatlas.org (Production)

External documentation

Atlas documentation and developer guides

Governed Atlas analytics, metadata, and provenance

Read-only structured data from the One Health Lyme Gap Atlas. Ordinary public reads are anonymous and require no API key.

Interpretation and reproducibility

V1 (/v1) is the HTTP contract version; the application version is separate. Read source, methodology, semantic/release versions, and limitations together. Surveillance floors and gap scores are not diagnoses, individual risk estimates, or causal claims. Null, zero, suppressed values, and no linked records have distinct meanings. Response time is not publisher freshness.

Queries and errors

Canonical collections use data, meta, and links; details use data. Pagination defaults to 100 items (maximum 500). Send opaque next_page_token as page_token with the same filters; null means exhaustion. Tokens bind to query/release and may expire on restart. Current-release observations require one measure, 1–500 county FIPS IDs, and a year or complete inclusive date range. The default pre-execution logical-result ceiling is 10,000, not truncation. Only the annual 2023 period is currently published; no strata are supported.

Errors use RFC 9457 application/problem+json with request_id for support. Canonical errors carry stable code values; legacy Atlas routes retain their existing error semantics (including 422 validation). Respect Retry-After on 429/503. Canonical metadata/observations cache for 60 seconds; supported detail resources return ETags and 304 on matching If-None-Match. See each operation for legacy cache and export behavior.

Contract consumers

Fumadocs, /docs, and /redoc consume the canonical public openapi.json at /openapi.json. Internal product operations are not part of this contract. Existing operation IDs remain stable for generated clients. Breaking public changes require an approved migration and deprecation plan; optional additive fields may appear within V1. Only separately approved ML outputs may be published. Internal conversational AI, literature retrieval, account, and feedback product routes are excluded.

Operations

discovery

Current-release indicators and measurable variables.

• GET /v1/indicators — Discover indicators — indicators_v1_indicators_get
• GET /v1/indicators/{indicator_id} — Get an indicator — indicator_v1_indicators__indicator_id__get
• GET /v1/measures — Discover measures — measures_v1_measures_get
• GET /v1/measures/{measure_id} — Get a measure — measure_v1_measures__measure_id__get

observations

Bounded county observations with explicit value states.

• GET /v1/observations — Query county observations — observations_v1_observations_get

provenance

Governed source and methodology identities and versions.

• GET /v1/methodologies/{methodology_id} — Get a methodology — methodology_v1_methodologies__methodology_id__get
• GET /v1/sources — Discover sources — sources_v1_sources_get
• GET /v1/sources/{source_id} — Get a source — source_v1_sources__source_id__get

geographies

Typed geography identity; delivery is not yet available.

• GET /v1/geographies/{geography_type}/{geography_id} — Get geography identity (delivery pending) — geography_v1_geographies__geography_type___geography_id__get

atlas

Existing release analytics and separate display geometry.

• GET /v1/atlas/geometry — Get county display geometry — geometry_v1_atlas_geometry_get
• GET /v1/atlas/metadata — Get Atlas release metadata — metadata_v1_atlas_metadata_get
• GET /v1/atlas/ranking.csv — Download filtered county rankings — ranking_csv_v1_atlas_ranking_csv_get
• GET /v1/atlas/scores — Get county gap scores — scores_v1_atlas_scores_get

counties

Existing county details and versioned PDF reports.

• GET /v1/counties/{fips} — Get county analytics and provenance — county_v1_counties__fips__get
• GET /v1/counties/{fips}/report.pdf — Download a county report — county_report_pdf_v1_counties__fips__report_pdf_get
• GET /v1/counties/{fips}/tier1-surveillance-priority — Get persisted Tier 1 model-assisted surveillance review priority — county_tier1_surveillance_priority_get

states

Existing state PDF reports.

• GET /v1/states/{state}/report.pdf — Download a state report — state_report_pdf_v1_states__state__report_pdf_get
• GET /v1/states/{state}/review — Review a state's county evidence — state_review_v1_states__state__review_get

Component schemas: Schemas (45).