API

HealthIT API

Query versioned healthcare-technology records with explicit evidence status, unknowns, and exclusion reasons.

Quick start

# Set this to the HealthIT preview or canonical origin you intend to query.
curl -s "$HEALTHIT_ORIGIN/api/v1/vendors" | jq '.snapshot_id, .vendors[0].documentary_gate_status'

Example response

{
  "documentary_gate_status": "passed",
  "scenario_eligibility": "eligible",
  "comparability_status": "not_comparable",
  "decision_readiness": "provisional",
  "critical_unknowns": ["deployment_traction"],
  "exclusion_reasons": [{ "code": "critical_unknown", "dimension": "deployment_traction" }],
  "snapshot_id": "snap_be69e7f46522da1a",
  "method_versions": { "score": "score-v0.2.0" }
}

Versioned endpoints

Method	Path	Contract
GET	/api/v1/vendors	Versioned vendor list with documentary gate, scenario eligibility, comparability, readiness, exclusions, and snapshot identity.
GET	/api/v1/vendors/{slug}	One vendor record with the same decision-state fields.
GET	/api/v1/categories	Workflow summaries bound to the current snapshot.
GET	/api/v1/signals	Forecast questions with probabilities and calibration fields.
GET	/.well-known/agents.json	Agent capability manifest: provenance rules, refusal boundaries, and every available surface.
GET	/api/v1/feedback	Self-describing private feedback contract for people and agents.
POST	/api/v1/feedback	Queue a non-PHI correction, evidence gap, missing product, usability report, or question. Never auto-published.
GET	/status.json	Application SHA, snapshot source SHA, snapshot id, cutoff, and counts.
GET	/llms.txt	Machine-discovery index.
GET	/openapi.json	OpenAPI 3.1 description of the v1 contract.

GET /api/v1/vendors

Versioned vendor list with documentary gate, scenario eligibility, comparability, readiness, exclusions, and snapshot identity.

GET /api/v1/vendors/{slug}

One vendor record with the same decision-state fields.

GET /api/v1/categories

Workflow summaries bound to the current snapshot.

GET /api/v1/signals

Forecast questions with probabilities and calibration fields.

GET /.well-known/agents.json

Agent capability manifest: provenance rules, refusal boundaries, and every available surface.

GET /api/v1/feedback

Self-describing private feedback contract for people and agents.

POST /api/v1/feedback

Queue a non-PHI correction, evidence gap, missing product, usability report, or question. Never auto-published.

GET /status.json

Application SHA, snapshot source SHA, snapshot id, cutoff, and counts.

GET /llms.txt

Machine-discovery index.

GET /openapi.json

OpenAPI 3.1 description of the v1 contract.

Deprecated compatibility endpoints

These remain for existing callers. New work should use /api/v1/*. Removal will be announced on this page first.

GET /api/vendors

Compatibility list. Prefer /api/v1/vendors. Removal will be announced here before fields disappear.

GET /api/vendors/{slug}

Compatibility detail. Prefer /api/v1/vendors/{slug}.

GET /api/categories

Compatibility categories. Prefer /api/v1/categories.

GET /api/signals

Compatibility signals. Prefer /api/v1/signals.

Decision-state definitions

documentary_gate_status, scenario_eligibility, comparability_status, and decision_readiness are separate. A product that passes the documentary gate is not automatically comparable.

Errors

Unknown slugs return HTTP 404. A v1 list that omitted exclusion_reasons on a non-comparable product would return HTTP 500 (fail closed).

Caching and rate limits

Current-data responses can be cached for five minutes; content-addressed snapshots use immutable caching. Public read endpoints have no fixed application quota. Feedback submissions are limited to ten requests per minute per IP in each serving region; excess requests receive HTTP 429. Keyed and paid access are planned and unavailable during the research preview.

Private feedback

Feedback is a non-PHI, moderated write surface. Read /api/v1/feedback before posting; corrections and evidence gaps require a source URL, and non_phi_confirmedmust be true. A 202 receipt means the private editorial handoff succeeded — it never means a claim or score changed.

Versioning and deprecations

v1 fields are additive. decision_admissible is preserved but ambiguous — prefer documentary_gate_status.

OpenAPI

/openapi.json describes the v1 contract.

Availability and planned paid access

This research preview does not issue API keys. See launch status.