--- title: "Vitals Vault Developer Portal | API, OpenAPI and MCP Docs" description: "Vitals Vault developer portal for the free Educational Biomarker API, the approval-gated partner FHIR R4 API, the OpenAPI specification, and the read-only MCP server." canonical: "https://www.vitalsvault.com/developers" last-updated: 2026-08-22 --- # Vitals Vault Developer Portal | API, OpenAPI and MCP Docs > Vitals Vault developer portal for the free Educational Biomarker API, the approval-gated partner FHIR R4 API, the OpenAPI specification, and the read-only MCP server. 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 API**lets 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](https://www.vitalsvault.com/llms.txt) and markdown content negotiation. ## 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](https://www.vitalsvault.com/openapi.json); 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](https://www.vitalsvault.com/api/fhir/r4/metadata). ### 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 1. A human applies through the [partner application form](https://www.vitalsvault.com/partners/apply). 2. Vitals Vault reviews the application and provisions credentials after approval. 3. 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/mcp`documentation 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](https://www.vitalsvault.com/developers/mcp) 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 - https://www.vitalsvault.com/llms.txt is the canonical index: what Vitals Vault is, when to use it, and links to every public section. https://www.vitalsvault.com/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](https://www.vitalsvault.com/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](mailto:support@vitalsvault.com). Security researchers should follow the disclosure process in the [Trust Center](https://www.vitalsvault.com/trust-center). --- Canonical HTML: https://www.vitalsvault.com/developers - [llms.txt](https://www.vitalsvault.com/llms.txt) - [sitemap.xml](https://www.vitalsvault.com/sitemap.xml) - [Developer portal](https://www.vitalsvault.com/developers)