Glossary
Names and concepts you will see across the docs.
API key (bk_*)
A long-lived secret that authenticates a CLI or MCP session against the Betterness API. Generated in the Console. Format: bk_ prefix followed by an opaque random string.
Audit trail
The append-only log of every tool call and API hit performed against your account. Includes timestamp, tool name, data categories accessed, agent identity (truncated key prefix), and request/response metadata. Inspectable from the Console.
Biological age
An assessment of how a user's biomarkers compare to their calendar age. Computed automatically from approved lab results.
Biomarker
A single measured analyte (e.g. Vitamin D, CRP, fasting glucose). In the API, biomarkers carry a value, unit, reference range, LOINC code, and category.
Consent grant
A record that authorizes a specific agent (identified by API key) to call specific tools and access specific data categories. Revocable from the Console.
Health profile
A structured questionnaire (~50 questions across 9 sections) covering medical history, lifestyle, diet, family history, prescriptions, and goals. Stored as a flat map of question ID → answer.
Lab order
The lifecycle object created when a user purchases a lab test through Betterness. Goes through statuses: Paid → Order Submitted → Requisition Created → Appointment Scheduled → Completed.
Lab record
Unified term covering both lab orders (placed through Betterness) and uploaded lab results (PDFs the user uploads). The getUserLabRecords tool returns both in one list with a source discriminator.
LOINC
The international standard code system for lab tests and observations. Each biomarker has a LOINC code; lab tests are filtered by LOINC slug.
MCP (Model Context Protocol)
An open protocol that lets AI clients call tools provided by external servers. The Betterness MCP server speaks HTTP at https://api.betterness.ai/mcp.
SmartListing
A wellness provider profile (clinic, gym, practitioner, brand) discoverable via the platform. Searchable by text, location, or following status.
Vital
The third-party provider Betterness uses for several wearable connections (Garmin, Oura, Withings, etc.). Apple Health uses a different connection path via the Betterness iOS app.