API

REST reference

base https://api.vladahealth.com·auth: Authorization: Bearer <key>·CORS: open·rate: 100 req/s per key·58 tools

Routes

Method	Path	Key	Returns
GET	`/v1/health`	no	liveness, version, tool count
GET	`/v1/tools`	optional	every tool with its JSON schema; with a key, the tools that key may call
GET	`/v1/tools/{name}/schema`	no	one tool's schema, as deployed
POST	`/v1/tools/{name}`	yes	the envelope; body = the tool's inputs
GET, POST	`/v1/price-proofs/{receipt_id}`	yes	a hospital-price receipt; /replay re-runs it on the same snapshot

Request

curl -X POST https://api.vladahealth.com/v1/tools/get_stars \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"H5521","year":2026}'

import requests
r = requests.post("https://api.vladahealth.com/v1/tools/get_stars",
                  headers={"Authorization": f"Bearer {KEY}"},
                  json={"contract_id": "H5521", "year": 2026})
answer = r.json()          # status, value, source, caveats, response_hash

const r = await fetch("https://api.vladahealth.com/v1/tools/get_stars", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ contract_id: "H5521", year: 2026 }),
});
const answer = await r.json();

Response envelope

Field	Type	Holds
`status`	enum	complete · partial · refused · failed · queued
`value`	object	rows or the figure, with its unit
`source`	object	dataset, publisher, vintage
`caveats`	string[]	read before citing
`invariants_applied`	string[]	rules honoured
`response_hash`	string	replayable
`refusal`	object	code, message, recover_with[]
`error`	object	code, message; correlation_id on a failure

HTTP status

Status	When
200	complete or partial
400	INVALID_ARGUMENTS, invalid_input
401	missing or unrecognised key
402	PLAN_REQUIRED
403	entitlement_denied, scope_forbidden
404	unknown_tool
422	every other refusal (NO_DATA, NO_COVERAGE, REQUIRED_FILTER_MISSING, ...)
429	DATA_ALLOWANCE_REACHED, rate_limit_exceeded
500	TOOL_FAILED, ENGINE_* (ours; correlation_id in the body)

Limits

Limit	Value	On the wire
Synchronous budget	40 s	SCAN_LIMIT_EXCEEDED; narrow the predicate
Bytes scanned per query	capped per workgroup	SCAN_LIMIT_EXCEEDED
Rows per call, rows per month	by plan	DATA_ALLOWANCE_REACHED with resets_on
Heavy price tools	one at a time per server	busy: wait 25 s, retry
Cache	15 min	identical call served from cache
Answer size	~50,000 chars	truncated; page or narrow

Gotchas that decide whether an answer resolves

Rule	Why
Pass `state` on hospital price lookups	resolution is state-scoped; without it the answer is a refusal naming the filter
NPI vs CCN	hospital tools are keyed by CCN (a facility), provider tools by NPI (a person or group); the same hospital appears under both; `resolve_provider` crosswalks them
Facility vs professional	a hospital file and a payer file carry different fees for the same code; compare within a class
Years are separate fields	plan year, rating year, measurement period and retrieval date; the answer names which
Star Ratings are contract-level	never a plan or county rating
Negotiated price is not out-of-pocket	what a plan agreed to pay a provider, not what a patient owes
Provenance on every result	`source`, `vintage`, `response_hash`; `prove_` and `replay_` turn a number into a re-runnable receipt

Per tool

What	Where
Inputs, defaults, outputs, limits, a real answer	/docs/tools
Machine-readable catalog	/api/catalog
Schemas, no key	https://api.vladahealth.com/v1/tools

This page as markdown: /docs-md/errors.md · every page in one file: /llms-full.txt