Home / Tools / REST quickstart

The Data API, before you talk to anyone.

Two doors to the same tools. Over MCP, an agent connects once and calls them by asking in plain English. Over REST, your code calls the same tools by name with an API key. Both return typed rows with the public source, its vintage, the methodology and a replayable hash on every answer.

1. Get a key

Create a free account at /data-access; it starts with $5 of queries, and verified .edu and .gov accounts get a free tier. Mint a key under your account (shown once). Plans and prices are on /pricing.

2. Endpoints

GET/v1/health

no key. Liveness.

GET/v1/tools

no key. Every served tool with its full JSON schema.

GET/v1/tools/{name}/schema

no key. One tool's schema, authoritative for what is deployed.

POST/v1/tools/{name}

Bearer key. Run the tool; body = the tool's input JSON.

GET|POST/v1/proofs/{receipt_id}

Bearer key. Fetch a commercial-price receipt; /replay re-runs it.

GET|POST/v1/price-proofs/{receipt_id}

Bearer key. Fetch a hospital-price receipt; /replay re-runs it.

Base URL https://api.vladahealth.com. CORS open. Rate limit 100 requests per second per key.

3. First call

# what does this payer pay this provider for this code, with proof
curl -X POST https://api.vladahealth.com/v1/tools/get_negotiated_rate \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer":"cigna","npi":"<10-digit NPI>","billing_code":"99213","state":"CA"}'

# the schema for any tool, no key
curl https://api.vladahealth.com/v1/tools/get_negotiated_rate/schema

4. Errors

Every error is one envelope: {"error":{"code":"...","message":"..."}}. A missing or bad key is 401; a tool your key is not entitled to is refused with a named code rather than an empty result; over the limit is 429 with rate_limit_exceeded. A question the data cannot answer is not an error: the tool returns not in the data with the coverage it checked, never a zero.

5. The gotchas that decide whether an answer resolves

Pass state on rate lookups. Resolution is state-scoped; without it you get no_match.
NPI vs CCN. Insurer and transparency-in-coverage tools are keyed by NPI (a provider, type 1 or 2); hospital tools are keyed by CCN (a facility). The same hospital appears under both. resolve_provider crosswalks them.
Facility vs professional. A hospital file and a payer file can carry different fees for the same code because they describe different services. Compare within a class, or use the tools that state the class.
Years are separate. Plan year, rating year, measurement period and retrieval date are distinct fields; the answer names which it is. Star Ratings are contract-level, never a plan or county rating.
Negotiated price is not out-of-pocket. A published negotiated rate is what a plan agreed to pay a provider, not what a patient owes.
Provenance is on every result (source, vintage, methodology, response_hash); the prove_* and replay_* tools turn a number into a re-runnable receipt.

6. Connect an agent instead (MCP)

# Claude Code
claude mcp add --transport http vlada https://mcp.vladahealth.com/mcp --header "Authorization: Bearer $VLADA_API_KEY"

# Claude Desktop, Cursor, VS Code, your own client: a remote Streamable-HTTP server at
#   https://mcp.vladahealth.com/mcp   with the same Authorization header
# ChatGPT (browser OAuth instead of a key header):
#   https://mcp-secure.vladahealth.com/mcp

Then ask. The discovery tools (find_data_sources, describe_schema, describe_data_source) tell the agent what exists; query_substrate runs guarded read-only SQL over the tables your key is entitled to; heavy pulls go through submit_query, poll_query, fetch_query. One-click setup per client is on /data-access.