Developers

Vitals Vault Developer Portal

Vitals Vault exposes two programmatic surfaces. The Educational Biomarker API is free, public, and needs no API key: it returns the same biomarker education, optimal ranges, and panel definitions that power this site. The Partner FHIR R4 APIlets approved care partners read a consenting member's lab results through OAuth 2.0 with per-resource scopes. Everything on this page is also readable by AI agents through llms.txt and markdown content negotiation.

Start here

Vitals Vault OpenAPI Specification
Resource page and machine-readable contract for the Educational Biomarker API.
OpenAPI 3.0 JSON
Raw machine-readable contract (also served at /api/v1/openapi-spec).
Vitals Vault API Reference
Server-rendered endpoint reference generated from the same OpenAPI document.
FHIR R4 CapabilityStatement
Resources, interactions, and security for the partner FHIR rail.
llms.txt
Agent-readable index of the site with a "when to use Vitals Vault" section.
auth.md
How agents authenticate: keyless Educational API, approval-gated partner FHIR OAuth.
pricing.md
Machine-readable panel prices.
Versioning policy
URL versioning, six-month deprecation notice, Sunset/Deprecation headers.
Agent Skills index
SKILL.md artifacts for biomarker lookup, panels, comparisons, and markdown reading.
Vitals Vault MCP Server
Resource page for the read-only Streamable HTTP server and its Educational Biomarker API tools.
MCP Protocol Endpoint
POST-only Streamable HTTP endpoint for product tools.
Vitals Vault MCP Server Card
Machine-readable description of the MCP server, tools, and transport.
sitemap.xml
Every indexable URL with lastmod dates.
Status page
Live platform status and incident history.

Educational Biomarker API

Base URL https://www.vitalsvault.com. Public read endpoints are GET; authenticated member write endpoints exist and are documented in the spec. Requests run over HTTPS and return JSON with a consistent { success, data, error? } envelope. There is no signup, no key, and no sales call: start with a single request.

curl -s https://www.vitalsvault.com/api/v1/biomarkers/categories \
  -H "Accept: application/json"

Endpoints

Method	Path	Returns
GET	/api/v1/biomarkers/categories	List biomarker categories (heart, metabolic, thyroid, hormones, ...)
GET	/api/v1/biomarkers/categories/{slug}	One category with its biomarkers
GET	/api/v1/biomarkers	Paginated biomarker list
GET	/api/v1/biomarkers/search?q=	Search biomarkers by name, alias, or keyword
GET	/api/v1/biomarkers/trending	Most-viewed biomarkers
GET	/api/v1/biomarkers/{slug}	Biomarker detail: description, units, standard and functional ranges by age and sex
GET	/api/v1/lab-packages	Essential, Advanced, and Max panel definitions and pricing
GET	/api/v1/lab-packages/{slug}	One panel with its included biomarkers

Limits and terms

Public Educational API GET endpoints share one budget of 100 requests per 15 minutes by default per client (IP), enforced across all servers. Exceeding the limit returns HTTP 429 with a Retry-After header and X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Content is educational and carries the same medical disclaimer as the site: it is not diagnosis or treatment advice.
Attribute Vitals Vault when you display the content and link back to the biomarker page where practical.
The full request and response schema lives in the OpenAPI document; admin endpoints listed there require an operator-issued bearer token; not part of the public surface.

Partner FHIR R4 API

Care navigators, health-record aggregators, and clinics can read a Vitals Vault member's lab results as standard FHIR R4 resources (Patient, Observation, DiagnosticReport) once that member has authorized the connection. The rail is enabled per environment and may be disabled on production. Every token is bound to one member, one application, and an explicit scope set.

Authentication

The partner's back channel pushes an authorization request to /api/oauth/par authenticated with the application's vvfhir_ bearer credential. The request carries the partner identity token and a PKCE S256 code challenge, and the response is a request_id.
The member is sent to /oauth/authorize with client_id and request_id and approves on the Vitals Vault consent screen.
The code is redeemed at /api/oauth/token (authorization_code + PKCE code_verifier, or a signed JWT client assertion for the attested exchange). Refresh uses refresh_token. Revoke at /api/oauth/revoke.
This handshake is documented for approved partners in the partner portal. It is not a generic RFC 8414 / RFC 9126 authorization server. Resource discovery is the CapabilityStatement.

Scopes

Access is least-privilege by construction. The scopes actually granted are the intersection of what the partner organisation is licensed for, what the specific application was registered with, and what the member was shown and approved. Requesting more than that ceiling fails with invalid_scope instead of being silently reduced.

Scope	Grants
patient/Patient.rs	Read and search the consenting patient’s Patient resource
patient/Observation.rs	Read and search that patient’s lab Observations (LOINC-coded)
patient/DiagnosticReport.rs	Read and search that patient’s DiagnosticReports

Getting access

A human applies through the partner application form.
Vitals Vault reviews the application and provisions credentials after approval.
There is no public sandbox or self-serve credential issuance. Production enablement is approval-gated per environment and partner.

Vitals Vault MCP Server

Agents can research biomarkers, compare Essential, Advanced, and Max, search the same currently orderable catalog used by checkout, request a controlled educational panel recommendation, or hand a person to Build Your Own Panel over Streamable HTTP. The product server is POST https://mcp.vitalsvault.com/mcpdocumentation search lives at POST https://mcp.vitalsvault.com/mcp/docs. Both are public, read-only, and unauthenticated. They share the Educational API rate limit. The MCP is stateless and accepts no private health data. Cart, account, order, and payment actions stay human-only.

One-minute setup and complete per-tool documentation includes schemas, examples, error behavior, provenance, and privacy boundaries.
Discovery: https://mcp.vitalsvault.com/.well-known/mcp/server-card.json and https://mcp.vitalsvault.com/.well-known/mcp.
Docs surface card: https://mcp.vitalsvault.com/.well-known/mcp/docs-server-card.json.
Protocol revision 2025-06-18. Send Accept: application/json on POST. GET /mcp returns 405 because the server is stateless and does not open an SSE stream.

For AI agents and crawlers

/llms.txt is the canonical index: what Vitals Vault is, when to use it, and links to every public section. /llms-full.txt carries the long-form reference.
Every public HTML page is also available as markdown. Send Accept: text/markdown and the response is text/markdown; charset=utf-8 with Vary: Accept, following acceptmarkdown.com. URL twins work too (/about-us.md, homepage /index.md). Unknown paths return a real HTTP 404 with a short markdown body that points back to this index.
Known AI crawler user-agents (GPTBot, ClaudeBot, Claude-User, Claude-SearchBot, ChatGPT-User, OAI-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended, ora-agent, ora-journey, DeepSeekBot) may receive markdown even without an Accept markdown preference, unless Accept explicitly prefers HTML over markdown. Googlebot and Bingbot always receive HTML. Disable with AGENT_BOT_MARKDOWN=false.
Major agent user-agents (GPTBot, ChatGPT-User, ClaudeBot, Google-Extended, PerplexityBot, and others) are explicitly allowed in robots.txt; nothing on the public site is behind a JavaScript-only path.

curl -s https://www.vitalsvault.com/biomarkers \
  -H "Accept: text/markdown"

Support

Questions, bug reports, or partnership requests: email support@vitalsvault.com. Security researchers should follow the disclosure process in the Trust Center.