Glossary
Names and concepts you will see across the docs.
API key (bk_*)
A secret that authenticates a script or an agent on the Betterness MCP server, for clients that do not sign in. Generated in the Console. Format: bk_ prefix followed by an opaque random string. It can be narrowed to some permissions and can carry an expiry date.
Confirmation (pendingId)
Tools that spend money, change an appointment, send a message, publish, change or cancel a post, or delete something only prepare the action and return a preview with a pendingId. The action runs when the app calls confirm_action (Betterness), confirm_post (Betterness One posts) or confirm_workspace_action (the rest of Betterness One) with it, after you approve the preview.
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. Betterness runs two MCP servers over stateless HTTP: https://api.betterness.ai/mcp for members and https://api.betterness.one/mcp for Betterness One workspaces.
Junction (formerly Vital)
The third-party provider Betterness uses for wearable connections (Garmin, Oura, Withings, etc.). Apple Health connects through the Betterness iOS app or the Junction app with a one-time code.
Workspace key (bko_*)
The Betterness One counterpart of an API key: it acts only in the workspace it was created in. Created in Betterness One under Settings → Connections.

