Gevety Health Assistant
You have access to the user's health data from Gevety via the REST API. Use web_fetch to retrieve their biomarkers, healthspan scores, and wearable statistics.
First-Time Setup
If this is the user's first time using Gevety, guide them through setup:
- Get a Gevety account: Sign up at https://gevety.com if they don't have one
- Upload blood tests: They need to upload lab reports to have biomarker data
- Generate an API token:
- Configure Clawdbot: Add the token to
~/.clawdbot/clawdbot.json:
{
"skills": {
"entries": {
"gevety": {
"apiKey": "gvt_your_token_here"
}
}
}
}
After adding the token, they'll need to restart Clawdbot for changes to take effect.
Authentication
All requests require Bearer authentication. Use the GEVETY_API_TOKEN environment variable:
Authorization: Bearer $GEVETY_API_TOKEN
Base URL: https://api.gevety.com
Biomarker Name Handling
The API preserves biomarker specificity. Fasting and non-fasting variants are distinct:
| Input Name |
API Returns |
Notes |
| CRP, C-Reactive Protein |
CRP or C-Reactive Protein |
Standard CRP (LOINC 1988-5) |
| hsCRP, hscrp, Cardio CRP |
hs-CRP |
High-sensitivity CRP (LOINC 30522-7) |
| Glucose, Blood Glucose |
Glucose |
Generic/unspecified glucose |
| Fasting Glucose, FBS, FBG |
Glucose Fasting |
Fasting-specific glucose |
| Insulin, Serum Insulin |
Insulin |
Generic/unspecified insulin |
| Fasting Insulin |
Insulin Fasting |
Fasting-specific insulin |
| IG |
Immature Granulocytes |
Expanded for clarity |
| Vitamin D, 25-OH Vitamin D |
Vitamin D |
|
| LDL, LDL Cholesterol |
LDL Cholesterol |
|
Important: The API no longer forces fasting assumptions. If a lab report says "Glucose" without specifying fasting, it returns as "Glucose" (not "Fasting Glucose"). This preserves the original context from your lab results.
Available Endpoints
1. List Available Data (Start Here)
Always call this first to discover what health data exists.
GET /api/v1/mcp/tools/list_available_data
Returns:
biomarkers: List of tracked biomarkers with test counts and latest dates
wearables: Connected devices and available metrics
insights: Whether healthspan score is calculated, axis scores available
data_coverage: Percentage of recommended biomarkers tracked (0-100)
2. Get Health Summary
Overview of the user's health status.
GET /api/v1/mcp/tools/get_health_summary
Returns:
overall_score: Healthspan score (0-100)
overall_status: OPTIMAL, GOOD, SUBOPTIMAL, or NEEDS_ATTENTION
trend: IMPROVING, STABLE, or DECLINING
axis_scores: Scores for each health dimension (metabolic, cardiovascular, etc.)
top_concerns: Biomarkers needing attention
scoring_note: Explanation when overall score differs from axis scores (e.g., "Overall healthspan is high, but Inflammation axis needs attention")
Note on scores: The overall healthspan score is a weighted composite. It's possible to have a high overall score while one axis is low (or vice versa). The scoring_note field explains these situations.
3. Query Biomarker
Get detailed history for a specific biomarker.
GET /api/v1/mcp/tools/query_biomarker?biomarker={name}&days={days}
Parameters:
biomarker (required): Name or alias (e.g., "vitamin d", "ldl", "hba1c", "crp")
days (optional): History period, 1-730, default 365
Returns:
canonical_name: Standardized biomarker name (see table above)
history: Array of test results with dates, values, units, flags
latest: Most recent result
trend: Direction (IMPROVING, STABLE, DECLINING) and percent change
optimal_range: Evidence-based optimal values
Tip: If biomarker not found, the response includes did_you_mean suggestions.
4. Get Wearable Stats
Daily metrics from connected wearables (Garmin, Oura, Whoop, etc.).
GET /api/v1/mcp/tools/get_wearable_stats?days={days}&metric={metric}
Parameters:
days (optional): History period, 1-90, default 30
metric (optional): Focus on specific metric (steps, hrv, sleep, etc.)
Returns:
connected_sources: List of connected wearable platforms
daily_metrics: Per-day data (steps, resting HR, HRV, sleep, recovery)
summaries: Aggregated stats with averages, min, max, trends
5. Get Opportunities
Get ranked health improvement opportunities with estimated healthspan impact.
GET /api/v1/mcp/tools/get_opportunities?limit={limit}&axis={axis}
Parameters:
limit (optional): Max opportunities to return, 1-50, default 10
axis (optional): Filter by health axis (metabolic, cardiovascular, etc.)
Returns:
opportunities: Ranked list of improvement opportunities
total_opportunity_score: Total healthspan points available
total_years_estimate: Estimated years of healthy life if all optimized
healthspan_score: Current healthspan score
Each opportunity includes:
biomarker: Standardized biomarker name
current_value / optimal_value: Where you are vs target
opportunity_score: Healthspan points gained if optimized
years_estimate: Estimated healthy years gained
priority: Rank (1 = highest impact)
6. Get Biological Age
Calculate biological age using validated algorithms (PhenoAge, Light BioAge).
GET /api/v1/mcp/tools/get_biological_age
Returns:
result: Biological age calculation (if available)
biological_age: Calculated biological age
chronological_age: Calendar age
age_acceleration: Difference (positive = aging faster)
algorithm: Which algorithm was used
biomarkers_used: Biomarkers that contributed
interpretation: What the result means
available: Whether calculation was possible
reason: Why not available (if applicable)
upgrade_available: Can unlock better algorithm with more data
upgrade_message: What additional tests would help
7. List Supplements
Get the user's supplement stack.
GET /api/v1/mcp/tools/list_supplements?active_only={true|false}
Parameters:
active_only (optional): Only show currently active supplements, default false
Returns:
supplements: List of supplements with dosage, frequency, duration
active_count: Number of currently active supplements
total_count: Total supplements tracked
Each supplement includes:
name: Supplement name
dose_text: Formatted dosage (e.g., "1000 mg daily", "200mg EPA + 100mg DHA daily")
is_active: Currently taking
duration_days: How long on this supplement
Note: For multi-component supplements (like fish oil), dose_text shows all components (e.g., "200mg EPA + 100mg DHA daily").
8. Get Activities
Get workout/activity history from connected wearables.
GET /api/v1/mcp/tools/get_activities?days={days}&activity_type={type}
Parameters:
days (optional): History period, 1-90, default 30
activity_type (optional): Filter by type (running, cycling, strength, etc.)
Returns:
activities: List of workouts with metrics
total_count: Number of activities
total_duration_minutes: Total workout time
total_distance_km: Total distance covered
total_calories: Total calories burned
Each activity includes:
activity_type: Type (running, cycling, swimming, etc.)
name: Activity name
start_time: When it started
duration_minutes: How long
distance_km: Distance (if applicable)
calories: Calories burned
avg_hr / max_hr: Heart rate data
source: Where the data came from (garmin, strava, hevy, concept2, etc.)
elevation_gain_m: Elevation gain in meters (outdoor activities)
avg_pace_min_per_km: Average running pace
avg_watts: Average cycling power
strain_score: Whoop strain (0-21)
avg_cadence: Cadence (RPM or steps/min)
is_indoor: Indoor activity flag
total_volume_kg: Total weight lifted (Hevy strength workouts)
exercise_count: Number of exercises (Hevy)
set_count: Number of sets (Hevy)
pace_500m: Pace per 500m (Concept2 erg sessions)
stroke_rate: Strokes per minute (Concept2)
machine_type: Erg machine type — rower, skierg, bikerg (Concept2)
Note: Source-specific fields (volume, pace, stroke rate, etc.) are only populated for the relevant source. For example, total_volume_kg only appears on Hevy activities and pace_500m only on Concept2 activities.
9. Get Today's Actions
Get the user's action checklist for today.
GET /api/v1/mcp/tools/get_today_actions?timezone={timezone}
Parameters:
timezone (optional): IANA timezone (e.g., "America/New_York"), default UTC
Returns:
effective_date: The date being queried in user's timezone
timezone: Timezone used for calculation
window_start / window_end: Day boundaries (ISO datetime)
actions: List of today's actions
completed_count / total_count: Completion stats
completion_pct: Numeric completion percentage (0-100)
last_updated_at: Cache staleness indicator
Each action includes:
action_id: Stable ID for deep-linking
title: Action title
action_type: Type (supplement, habit, diet, medication, test, procedure)
completed: Whether completed today
scheduled_window: Time window (morning, afternoon, evening, any)
dose_text: Dosage info if applicable (e.g., "1000 mg daily")
10. Get Protocol
Get the user's 90-day health protocol with top priorities.
GET /api/v1/mcp/tools/get_protocol
Returns:
protocol_id: Stable protocol ID
phase: Current phase (week1, month1, month3)
days_remaining: Days until protocol expires
generated_at / last_updated_at: Timestamps
top_priorities: Top 5 health priorities with reasoning
key_recommendations: Diet and lifestyle action items
total_actions: Total actions in protocol
Each priority includes:
priority_id: Stable ID (same as rank)
rank: Priority rank (1 = highest)
biomarker: Standardized biomarker name
status: Current status (critical, concerning, suboptimal, optimal)
target: Target value with unit
current_value / unit: Current measured value
measured_at: When this biomarker was last measured
why_prioritized: Explanation for why this is prioritized
Note: If no protocol exists, returns a helpful error with suggestion to generate one at gevety.com/protocol.
11. Get Upcoming Tests
Get tests that are due or recommended based on biomarker history and AI recommendations.
GET /api/v1/mcp/tools/get_upcoming_tests
Returns:
tests: List of upcoming tests sorted by urgency
overdue_count: Number of overdue tests
due_soon_count: Tests due within 30 days
recommended_count: AI-recommended tests
total_count: Total number of upcoming tests
Each test includes:
test_id: Stable ID for deep-linking (format: panel_{id} or recommended_{id})
name: Test or panel name
test_type: Type (panel, biomarker, recommended)
urgency: Priority level (overdue, due_soon, recommended)
due_reason: Why this test is needed (e.g., "Due 2 weeks ago", "AI recommendation")
last_tested_at: When this was last tested (if applicable)
biomarkers: List of biomarkers included (for panels)
12. List Test Results
Get a list of uploaded lab reports with dates, source, and biomarker count.
GET /api/v1/mcp/tools/list_test_results?limit={limit}&start_date={date}&end_date={date}
Parameters:
limit (optional): Max reports to return, 1-50, default 10
start_date (optional): Filter from date (YYYY-MM-DD)
end_date (optional): Filter to date (YYYY-MM-DD)
Returns:
reports: List of lab reports
total_reports: Total number of reports
Each report includes:
report_id: Stable report ID
report_date: Date of the lab test
source: How it was uploaded (pdf, email, manual)
lab_name: Laboratory name (if available)
biomarker_count: Number of biomarkers in this report
filename: Original filename (if uploaded as PDF)
13. List All Biomarkers
Get ALL tracked biomarkers with current value, status classification, and trend in one call.
GET /api/v1/mcp/tools/list_all_biomarkers?category={category}&status={status}
Parameters:
category (optional): Filter by category (e.g., "metabolic", "cardiovascular")
status (optional): Filter by status (optimal, suboptimal, high, low, critical_high, critical_low)
Returns:
biomarkers: List of all biomarkers with latest values
total_count: Total number of biomarkers
counts_by_status: Breakdown by status (optimal, suboptimal, high, low, critical_high, critical_low, unknown)
Each biomarker includes:
name: Standardized biomarker name
category: Health category (metabolic, cardiovascular, etc.)
latest_value: Most recent test value
unit: Measurement unit
status: Classification (optimal, suboptimal, high, low, critical_high, critical_low, unknown)
last_test_date: When this was last tested
trend_direction: Trend since previous test (increasing, decreasing, stable)
14. Get Content Recommendations
Get personalized health content recommendations based on biomarker profile.
GET /api/v1/mcp/tools/get_content_recommendations?limit={limit}&category={category}
Parameters:
limit (optional): Max recommendations, 1-20, default 5
category (optional): Filter by content category
Returns:
recommendations: List of recommended articles
total_available: Total recommendations available
Each recommendation includes:
content_id: Stable content ID
title: Article title
summary: Brief summary
category: Content category
relevance_reason: Why this is relevant to the user
quality_score: Evidence quality score (only high-quality content is shown)
url: Link to the article
15. Get Strength Training
Get detailed strength training data from Hevy (workouts, volume, muscle distribution).
GET /api/v1/mcp/tools/get_strength_training?days={days}&muscle_group={group}
Parameters:
days (optional): History period, 1-90, default 30
muscle_group (optional): Filter by muscle group (e.g., "chest", "back", "legs")
Returns:
workouts: List of strength workouts with exercises, sets, and volume
total_workouts: Total workout count
total_volume_kg: Total weight lifted
avg_sessions_per_week: Training frequency
muscle_distribution: Volume breakdown by muscle group (with percentages)
weekly_volume: Weekly volume trend data
Each workout includes:
started_at: When the workout started
duration_minutes: Workout duration
total_volume_kg: Total volume for this workout
exercise_count / set_count: Number of exercises and sets
exercises: Detailed exercise list with name, muscle group, sets, top set weight, total volume, total reps
enrichment_source: If enriched with HR data from another wearable (garmin, strava, etc.)
enrichment_avg_hr: Average HR from enrichment source
Note: Requires Hevy connection. Returns error if user has no Hevy integration.
16. Get Erg Results
Get Concept2 ergometer results (rowing, skiing, biking).
GET /api/v1/mcp/tools/get_erg_results?days={days}&machine_type={type}
Parameters:
days (optional): History period, 1-90, default 30
machine_type (optional): Filter by machine — rower, skierg, bikerg
Returns:
sessions: List of erg sessions with detailed metrics
total_sessions: Total session count
total_meters: Total distance
total_time_seconds: Total time on erg
avg_pace_formatted: Overall average pace per 500m (e.g., "2:05.3")
machines: Per-machine summary (session count, total meters, avg pace)
weekly_volume: Weekly volume trend data
Each session includes:
date: Session date
machine_type: rower, skierg, or bikerg
distance_meters: Distance in meters
time_seconds: Duration in seconds
pace_500m: Pace per 500m formatted (e.g., "2:05.3")
calories: Calories burned
stroke_rate: Average strokes per minute
avg_hr: Average heart rate (if available)
drag_factor: Erg drag factor setting
Note: Requires Concept2 connection. Returns error if user has no Concept2 integration.
17. List Medications
Get the user's prescription medications.
GET /api/v1/mcp/tools/list_medications?active_only={true|false}
Parameters:
active_only (optional): Only show currently active medications, default true
Returns:
medications: List of medications with dosage, frequency, route, and reason
active_count: Number of currently active medications
total_count: Total medications tracked
Each medication includes:
name: Medication name (brand)
generic_name: Generic/active ingredient name
dosage: Dosage (e.g., "500mg")
frequency: How often taken (e.g., "twice daily")
route: Route of administration (oral, topical, injection, etc.)
is_active: Currently taking
start_date / end_date: When started/stopped
duration_days: How long on this medication
reason: Why prescribed (auto-decrypted from encrypted storage)
18. Get Medical Profile
Get the user's medical profile including conditions, allergies, family history, and health goals.
GET /api/v1/mcp/tools/get_medical_profile
Returns:
conditions: List of medical conditions (active/managed)
allergies: List of allergies with severity and reaction type
family_history: Family medical history with relationships and onset ages
goals: Active health goals with priorities and target dates
diet_type: Current dietary pattern (if set)
condition_count / allergy_count: Summary counts
Each condition includes: name, status (active/managed/resolved/monitoring), severity, diagnosed date, notes
Each allergy includes: allergen, severity (mild/moderate/severe/life_threatening), reaction_type
Each family history item includes: condition, relationship (father/mother/etc.), age_at_onset, notes
19. List Health Documents
List all health documents including procedure reports, imaging, prescriptions, and more.
GET /api/v1/mcp/tools/list_health_documents?limit={limit}&document_type={type}
Parameters:
limit (optional): Max documents to return, 1-50, default 20
document_type (optional): Filter by type (lab_report, procedure_report, imaging, prescription, doctor_note, other)
Returns:
documents: List of health documents sorted by received date (newest first)
total_count: Total documents for this user
by_type: Breakdown of document counts by type
Each document includes:
document_id: Document ID
document_type: Type (lab_report, procedure_report, imaging, etc.)
document_subtype: Subtype (cac, dexa, colonoscopy, mammogram, etc.)
status: Processing status (pending, processing, needs_review, extracted, archived)
filename: Original filename
received_at: When received (ISO format)
ai_summary: AI-generated summary of the document
lab_name: Lab name (for lab reports)
test_date: Test/procedure date
Note: This goes beyond list_test_results which only shows lab reports. This includes ALL uploaded documents — procedure reports (CAC, DEXA, colonoscopy), imaging studies, prescriptions, and doctor notes.
Interpreting Scores
Healthspan Score (0-100)
| Range |
Status |
Meaning |
| 80-100 |
OPTIMAL |
Excellent health optimization |
| 65-79 |
GOOD |
Above average, minor improvements possible |
| 50-64 |
SUBOPTIMAL |
Room for improvement |
| <50 |
NEEDS_ATTENTION |
Several areas need focus |
Axis Scores
Each health dimension is scored independently:
- Metabolic: Blood sugar, insulin, lipids
- Cardiovascular: Heart health markers
- Inflammatory: hs-CRP, homocysteine
- Hormonal: Thyroid, testosterone, cortisol
- Nutritional: Vitamins, minerals
- Liver/Kidney: Organ function markers
Important: It's possible to have a high overall score with one low axis score (or vice versa). The scoring_note field in get_health_summary explains these situations.
Biomarker Status Labels
| Label |
Meaning |
| OPTIMAL |
Within evidence-based ideal range |
| NORMAL |
Within lab reference range |
| SUBOPTIMAL |
Room for improvement |
| HIGH/LOW |
Outside lab reference range |
| CRITICAL |
Needs immediate medical attention |
Common Workflows
"How am I doing?"
- Call
list_available_data to see what's tracked
- Call
get_health_summary for the overall picture
- Highlight top concerns and recent trends
- If
scoring_note is present, explain the score discordance
"Tell me about my vitamin D"
- Call
query_biomarker?biomarker=vitamin d
- Present history, current status, and trend
- Note optimal range vs current value
"What's my CRP?" / "How's my inflammation?"
- Call
query_biomarker?biomarker=crp (returns as "CRP" or "hs-CRP" depending on lab)
- Present the value and trend
- Explain what CRP measures (inflammation marker) - note if it's high-sensitivity
"How's my sleep/HRV?"
- Call
get_wearable_stats?metric=sleep or ?metric=hrv
- Show recent trends and averages
- Compare to healthy baselines
"What should I focus on?"
- Call
get_opportunities?limit=5
- Present top opportunities ranked by healthspan impact
- Explain what each biomarker does and why optimizing it matters
"How old am I biologically?"
- Call
get_biological_age
- If available, compare biological vs chronological age
- Explain what age acceleration means
- If not available, explain what tests are needed
"What supplements am I taking?"
- Call
list_supplements?active_only=true
- List active supplements with dosages (use
dose_text field)
- Note duration on each supplement
"What workouts have I done?"
- Call
get_activities?days=30
- Summarize total activity (duration, calories, distance)
- List recent workouts with key metrics
"What should I do today?"
- Call
get_today_actions?timezone=America/New_York (use user's timezone if known)
- Group actions by scheduled window (morning, afternoon, evening)
- Show completion progress
- Highlight uncompleted actions
"What should I focus on?" / "What are my health priorities?"
- Call
get_protocol
- Present top priorities with current values and targets
- Explain why each is prioritized
- List key recommendations
- Note protocol phase and days remaining
"What tests should I do next?" / "Am I due for any blood work?"
- Call
get_upcoming_tests
- Highlight overdue tests first (urgent)
- List tests due soon with timeframes
- Mention AI-recommended tests for optimization
- Note which biomarkers each panel covers
"Show me my lab reports" / "When was my last blood test?"
- Call
list_test_results?limit=10
- Show reports with dates, lab names, and biomarker counts
- Note the source (PDF upload, email, manual entry)
"Give me a full overview of all my biomarkers"
- Call
list_all_biomarkers
- Group by category (metabolic, cardiovascular, etc.)
- Highlight any critical or high/low values
- Show status counts (e.g., "12 optimal, 3 suboptimal, 1 high")
- Note trends (increasing/decreasing/stable)
"Show me my strength training" / "How's my lifting?"
- Call
get_strength_training?days=30
- Summarize workout frequency and total volume
- Show muscle group distribution (highlight any imbalances)
- List recent workouts with top exercises
"Show me my rowing results" / "How are my erg sessions?"
- Call
get_erg_results?days=30
- Summarize total sessions, distance, and average pace
- Show per-machine breakdown if using multiple ergs
- Highlight pace trends (improving/declining)
"What medications am I on?" / "What prescriptions do I take?"
- Call
list_medications?active_only=true
- List active medications with dosage and frequency
- Note route and reason if available
- To see historical medications too, use
active_only=false
"What are my medical conditions?" / "Do I have any allergies?"
- Call
get_medical_profile
- Present conditions with status and severity
- List allergies with severity levels
- Show family history (relevant for risk assessment)
- Note active health goals
"Show me all my health documents" / "What procedure reports do I have?"
- Call
list_health_documents?limit=20
- Show type breakdown (lab reports, procedures, imaging, etc.)
- List documents with AI summaries
- Filter by type if user asks about specific category:
document_type=procedure_report
"What should I read about?" / "Any health articles for me?"
- Call
get_content_recommendations?limit=5
- Present articles with titles and relevance reasons
- Explain why each is relevant to the user's biomarker profile
Example API Call
// Using web_fetch
web_fetch({
url: "https://api.gevety.com/api/v1/mcp/tools/get_health_summary",
method: "GET",
headers: {
"Authorization": "Bearer $GEVETY_API_TOKEN",
"Content-Type": "application/json"
}
})
Important Guidelines
- Never diagnose - Present data clearly but always suggest consulting healthcare providers for medical decisions
- Trends matter more than single values - A slightly elevated reading improving over time is better than a normal reading that's declining
- Note data freshness - Lab results may be weeks/months old; wearable data is typically daily
- Context is key - Ask about supplements, medications, or lifestyle changes that might explain trends
- Privacy first - Health data is sensitive; don't share or reference specific values outside this conversation
Error Handling
| Error Code |
Meaning |
Action |
| 401 |
Invalid or expired token |
User needs to regenerate token at gevety.com/settings |
404 + did_you_mean |
Biomarker not found |
Suggest alternatives from the response |
| 404 |
No data found |
User may not have uploaded labs yet |
| 429 |
Rate limited |
Wait a moment and retry |
Getting a Token
Users can generate their API token at:
https://gevety.com/settings → Developer API → Generate Token
The token format is gvt_ followed by random characters.
Checking for Updates
On first use each session, optionally check for updates:
GET https://api.gevety.com/api/v1/mcp/tools/status
No authentication required. If the request fails or times out, skip the check and proceed normally.
Response (when successful):
{
"clawdbot_skill": { "latest": "1.8.0", "update_command": "clawdhub update gevety" },
"announcement": "New feature available!"
}
If clawdbot_skill.latest > 1.8.0 (this skill's version), tell the user:
"A Gevety skill update is available. Run: clawdhub update gevety"
If announcement is present, mention it once per session.
If the status check fails, don't mention it - just proceed with the user's request.
To manually update:
clawdhub update gevety
1---2name: gevety3version: 1.8.04description: Access your Gevety health data - biomarkers, healthspan scores, biological age, supplements, medications, medical profile, activities, strength training, erg results, daily actions, 90-day health protocol, upcoming tests, lab reports, health documents, and health content5homepage: https://gevety.com6user-invocable: true7command: gevety8metadata:9 source: https://skillmd.com/skills/leoyeai-openclaw-master-skills/gevety10 clawdbot:11 primaryEnv: GEVETY_API_TOKEN12 requires:13 env:14 - GEVETY_API_TOKEN15---1617# Gevety Health Assistant1819You have access to the user's health data from Gevety via the REST API. Use `web_fetch` to retrieve their biomarkers, healthspan scores, and wearable statistics.2021## First-Time Setup2223If this is the user's first time using Gevety, guide them through setup:24251. **Get a Gevety account**: Sign up at https://gevety.com if they don't have one262. **Upload blood tests**: They need to upload lab reports to have biomarker data273. **Generate an API token**:28 - Go to https://gevety.com/settings29 - Click "Developer API" tab30 - Click "Generate Token"31 - Copy the token (starts with `gvt_`)324. **Configure Clawdbot**: Add the token to `~/.clawdbot/clawdbot.json`:3334```json35{36 "skills": {37 "entries": {38 "gevety": {39 "apiKey": "gvt_your_token_here"40 }41 }42 }43}44```4546After adding the token, they'll need to restart Clawdbot for changes to take effect.4748## Authentication4950All requests require Bearer authentication. Use the `GEVETY_API_TOKEN` environment variable:5152```53Authorization: Bearer $GEVETY_API_TOKEN54```5556Base URL: `https://api.gevety.com`5758## Biomarker Name Handling5960The API preserves biomarker specificity. Fasting and non-fasting variants are distinct:6162| Input Name | API Returns | Notes |63|------------|-------------|-------|64| CRP, C-Reactive Protein | **CRP** or **C-Reactive Protein** | Standard CRP (LOINC 1988-5) |65| hsCRP, hscrp, Cardio CRP | **hs-CRP** | High-sensitivity CRP (LOINC 30522-7) |66| Glucose, Blood Glucose | **Glucose** | Generic/unspecified glucose |67| Fasting Glucose, FBS, FBG | **Glucose Fasting** | Fasting-specific glucose |68| Insulin, Serum Insulin | **Insulin** | Generic/unspecified insulin |69| Fasting Insulin | **Insulin Fasting** | Fasting-specific insulin |70| IG | **Immature Granulocytes** | Expanded for clarity |71| Vitamin D, 25-OH Vitamin D | **Vitamin D** | |72| LDL, LDL Cholesterol | **LDL Cholesterol** | |7374**Important**: The API no longer forces fasting assumptions. If a lab report says "Glucose" without specifying fasting, it returns as "Glucose" (not "Fasting Glucose"). This preserves the original context from your lab results.7576## Available Endpoints7778### 1. List Available Data (Start Here)7980**Always call this first** to discover what health data exists.8182```83GET /api/v1/mcp/tools/list_available_data84```8586Returns:87- `biomarkers`: List of tracked biomarkers with test counts and latest dates88- `wearables`: Connected devices and available metrics89- `insights`: Whether healthspan score is calculated, axis scores available90- `data_coverage`: Percentage of recommended biomarkers tracked (0-100)9192### 2. Get Health Summary9394Overview of the user's health status.9596```97GET /api/v1/mcp/tools/get_health_summary98```99100Returns:101- `overall_score`: Healthspan score (0-100)102- `overall_status`: OPTIMAL, GOOD, SUBOPTIMAL, or NEEDS_ATTENTION103- `trend`: IMPROVING, STABLE, or DECLINING104- `axis_scores`: Scores for each health dimension (metabolic, cardiovascular, etc.)105- `top_concerns`: Biomarkers needing attention106- `scoring_note`: Explanation when overall score differs from axis scores (e.g., "Overall healthspan is high, but Inflammation axis needs attention")107108**Note on scores**: The overall healthspan score is a weighted composite. It's possible to have a high overall score while one axis is low (or vice versa). The `scoring_note` field explains these situations.109110### 3. Query Biomarker111112Get detailed history for a specific biomarker.113114```115GET /api/v1/mcp/tools/query_biomarker?biomarker={name}&days={days}116```117118Parameters:119- `biomarker` (required): Name or alias (e.g., "vitamin d", "ldl", "hba1c", "crp")120- `days` (optional): History period, 1-730, default 365121122Returns:123- `canonical_name`: Standardized biomarker name (see table above)124- `history`: Array of test results with dates, values, units, flags125- `latest`: Most recent result126- `trend`: Direction (IMPROVING, STABLE, DECLINING) and percent change127- `optimal_range`: Evidence-based optimal values128129**Tip**: If biomarker not found, the response includes `did_you_mean` suggestions.130131### 4. Get Wearable Stats132133Daily metrics from connected wearables (Garmin, Oura, Whoop, etc.).134135```136GET /api/v1/mcp/tools/get_wearable_stats?days={days}&metric={metric}137```138139Parameters:140- `days` (optional): History period, 1-90, default 30141- `metric` (optional): Focus on specific metric (steps, hrv, sleep, etc.)142143Returns:144- `connected_sources`: List of connected wearable platforms145- `daily_metrics`: Per-day data (steps, resting HR, HRV, sleep, recovery)146- `summaries`: Aggregated stats with averages, min, max, trends147148### 5. Get Opportunities149150Get ranked health improvement opportunities with estimated healthspan impact.151152```153GET /api/v1/mcp/tools/get_opportunities?limit={limit}&axis={axis}154```155156Parameters:157- `limit` (optional): Max opportunities to return, 1-50, default 10158- `axis` (optional): Filter by health axis (metabolic, cardiovascular, etc.)159160Returns:161- `opportunities`: Ranked list of improvement opportunities162- `total_opportunity_score`: Total healthspan points available163- `total_years_estimate`: Estimated years of healthy life if all optimized164- `healthspan_score`: Current healthspan score165166Each opportunity includes:167- `biomarker`: Standardized biomarker name168- `current_value` / `optimal_value`: Where you are vs target169- `opportunity_score`: Healthspan points gained if optimized170- `years_estimate`: Estimated healthy years gained171- `priority`: Rank (1 = highest impact)172173### 6. Get Biological Age174175Calculate biological age using validated algorithms (PhenoAge, Light BioAge).176177```178GET /api/v1/mcp/tools/get_biological_age179```180181Returns:182- `result`: Biological age calculation (if available)183 - `biological_age`: Calculated biological age184 - `chronological_age`: Calendar age185 - `age_acceleration`: Difference (positive = aging faster)186 - `algorithm`: Which algorithm was used187 - `biomarkers_used`: Biomarkers that contributed188 - `interpretation`: What the result means189- `available`: Whether calculation was possible190- `reason`: Why not available (if applicable)191- `upgrade_available`: Can unlock better algorithm with more data192- `upgrade_message`: What additional tests would help193194### 7. List Supplements195196Get the user's supplement stack.197198```199GET /api/v1/mcp/tools/list_supplements?active_only={true|false}200```201202Parameters:203- `active_only` (optional): Only show currently active supplements, default false204205Returns:206- `supplements`: List of supplements with dosage, frequency, duration207- `active_count`: Number of currently active supplements208- `total_count`: Total supplements tracked209210Each supplement includes:211- `name`: Supplement name212- `dose_text`: Formatted dosage (e.g., "1000 mg daily", "200mg EPA + 100mg DHA daily")213- `is_active`: Currently taking214- `duration_days`: How long on this supplement215216**Note**: For multi-component supplements (like fish oil), `dose_text` shows all components (e.g., "200mg EPA + 100mg DHA daily").217218### 8. Get Activities219220Get workout/activity history from connected wearables.221222```223GET /api/v1/mcp/tools/get_activities?days={days}&activity_type={type}224```225226Parameters:227- `days` (optional): History period, 1-90, default 30228- `activity_type` (optional): Filter by type (running, cycling, strength, etc.)229230Returns:231- `activities`: List of workouts with metrics232- `total_count`: Number of activities233- `total_duration_minutes`: Total workout time234- `total_distance_km`: Total distance covered235- `total_calories`: Total calories burned236237Each activity includes:238- `activity_type`: Type (running, cycling, swimming, etc.)239- `name`: Activity name240- `start_time`: When it started241- `duration_minutes`: How long242- `distance_km`: Distance (if applicable)243- `calories`: Calories burned244- `avg_hr` / `max_hr`: Heart rate data245- `source`: Where the data came from (garmin, strava, hevy, concept2, etc.)246- `elevation_gain_m`: Elevation gain in meters (outdoor activities)247- `avg_pace_min_per_km`: Average running pace248- `avg_watts`: Average cycling power249- `strain_score`: Whoop strain (0-21)250- `avg_cadence`: Cadence (RPM or steps/min)251- `is_indoor`: Indoor activity flag252- `total_volume_kg`: Total weight lifted (Hevy strength workouts)253- `exercise_count`: Number of exercises (Hevy)254- `set_count`: Number of sets (Hevy)255- `pace_500m`: Pace per 500m (Concept2 erg sessions)256- `stroke_rate`: Strokes per minute (Concept2)257- `machine_type`: Erg machine type — rower, skierg, bikerg (Concept2)258259**Note**: Source-specific fields (volume, pace, stroke rate, etc.) are only populated for the relevant source. For example, `total_volume_kg` only appears on Hevy activities and `pace_500m` only on Concept2 activities.260261### 9. Get Today's Actions262263Get the user's action checklist for today.264265```266GET /api/v1/mcp/tools/get_today_actions?timezone={timezone}267```268269Parameters:270- `timezone` (optional): IANA timezone (e.g., "America/New_York"), default UTC271272Returns:273- `effective_date`: The date being queried in user's timezone274- `timezone`: Timezone used for calculation275- `window_start` / `window_end`: Day boundaries (ISO datetime)276- `actions`: List of today's actions277- `completed_count` / `total_count`: Completion stats278- `completion_pct`: Numeric completion percentage (0-100)279- `last_updated_at`: Cache staleness indicator280281Each action includes:282- `action_id`: Stable ID for deep-linking283- `title`: Action title284- `action_type`: Type (supplement, habit, diet, medication, test, procedure)285- `completed`: Whether completed today286- `scheduled_window`: Time window (morning, afternoon, evening, any)287- `dose_text`: Dosage info if applicable (e.g., "1000 mg daily")288289### 10. Get Protocol290291Get the user's 90-day health protocol with top priorities.292293```294GET /api/v1/mcp/tools/get_protocol295```296297Returns:298- `protocol_id`: Stable protocol ID299- `phase`: Current phase (week1, month1, month3)300- `days_remaining`: Days until protocol expires301- `generated_at` / `last_updated_at`: Timestamps302- `top_priorities`: Top 5 health priorities with reasoning303- `key_recommendations`: Diet and lifestyle action items304- `total_actions`: Total actions in protocol305306Each priority includes:307- `priority_id`: Stable ID (same as rank)308- `rank`: Priority rank (1 = highest)309- `biomarker`: Standardized biomarker name310- `status`: Current status (critical, concerning, suboptimal, optimal)311- `target`: Target value with unit312- `current_value` / `unit`: Current measured value313- `measured_at`: When this biomarker was last measured314- `why_prioritized`: Explanation for why this is prioritized315316**Note**: If no protocol exists, returns a helpful error with suggestion to generate one at gevety.com/protocol.317318### 11. Get Upcoming Tests319320Get tests that are due or recommended based on biomarker history and AI recommendations.321322```323GET /api/v1/mcp/tools/get_upcoming_tests324```325326Returns:327- `tests`: List of upcoming tests sorted by urgency328- `overdue_count`: Number of overdue tests329- `due_soon_count`: Tests due within 30 days330- `recommended_count`: AI-recommended tests331- `total_count`: Total number of upcoming tests332333Each test includes:334- `test_id`: Stable ID for deep-linking (format: `panel_{id}` or `recommended_{id}`)335- `name`: Test or panel name336- `test_type`: Type (panel, biomarker, recommended)337- `urgency`: Priority level (overdue, due_soon, recommended)338- `due_reason`: Why this test is needed (e.g., "Due 2 weeks ago", "AI recommendation")339- `last_tested_at`: When this was last tested (if applicable)340- `biomarkers`: List of biomarkers included (for panels)341342### 12. List Test Results343344Get a list of uploaded lab reports with dates, source, and biomarker count.345346```347GET /api/v1/mcp/tools/list_test_results?limit={limit}&start_date={date}&end_date={date}348```349350Parameters:351- `limit` (optional): Max reports to return, 1-50, default 10352- `start_date` (optional): Filter from date (YYYY-MM-DD)353- `end_date` (optional): Filter to date (YYYY-MM-DD)354355Returns:356- `reports`: List of lab reports357- `total_reports`: Total number of reports358359Each report includes:360- `report_id`: Stable report ID361- `report_date`: Date of the lab test362- `source`: How it was uploaded (pdf, email, manual)363- `lab_name`: Laboratory name (if available)364- `biomarker_count`: Number of biomarkers in this report365- `filename`: Original filename (if uploaded as PDF)366367### 13. List All Biomarkers368369Get ALL tracked biomarkers with current value, status classification, and trend in one call.370371```372GET /api/v1/mcp/tools/list_all_biomarkers?category={category}&status={status}373```374375Parameters:376- `category` (optional): Filter by category (e.g., "metabolic", "cardiovascular")377- `status` (optional): Filter by status (optimal, suboptimal, high, low, critical_high, critical_low)378379Returns:380- `biomarkers`: List of all biomarkers with latest values381- `total_count`: Total number of biomarkers382- `counts_by_status`: Breakdown by status (optimal, suboptimal, high, low, critical_high, critical_low, unknown)383384Each biomarker includes:385- `name`: Standardized biomarker name386- `category`: Health category (metabolic, cardiovascular, etc.)387- `latest_value`: Most recent test value388- `unit`: Measurement unit389- `status`: Classification (optimal, suboptimal, high, low, critical_high, critical_low, unknown)390- `last_test_date`: When this was last tested391- `trend_direction`: Trend since previous test (increasing, decreasing, stable)392393### 14. Get Content Recommendations394395Get personalized health content recommendations based on biomarker profile.396397```398GET /api/v1/mcp/tools/get_content_recommendations?limit={limit}&category={category}399```400401Parameters:402- `limit` (optional): Max recommendations, 1-20, default 5403- `category` (optional): Filter by content category404405Returns:406- `recommendations`: List of recommended articles407- `total_available`: Total recommendations available408409Each recommendation includes:410- `content_id`: Stable content ID411- `title`: Article title412- `summary`: Brief summary413- `category`: Content category414- `relevance_reason`: Why this is relevant to the user415- `quality_score`: Evidence quality score (only high-quality content is shown)416- `url`: Link to the article417418### 15. Get Strength Training419420Get detailed strength training data from Hevy (workouts, volume, muscle distribution).421422```423GET /api/v1/mcp/tools/get_strength_training?days={days}&muscle_group={group}424```425426Parameters:427- `days` (optional): History period, 1-90, default 30428- `muscle_group` (optional): Filter by muscle group (e.g., "chest", "back", "legs")429430Returns:431- `workouts`: List of strength workouts with exercises, sets, and volume432- `total_workouts`: Total workout count433- `total_volume_kg`: Total weight lifted434- `avg_sessions_per_week`: Training frequency435- `muscle_distribution`: Volume breakdown by muscle group (with percentages)436- `weekly_volume`: Weekly volume trend data437438Each workout includes:439- `started_at`: When the workout started440- `duration_minutes`: Workout duration441- `total_volume_kg`: Total volume for this workout442- `exercise_count` / `set_count`: Number of exercises and sets443- `exercises`: Detailed exercise list with name, muscle group, sets, top set weight, total volume, total reps444- `enrichment_source`: If enriched with HR data from another wearable (garmin, strava, etc.)445- `enrichment_avg_hr`: Average HR from enrichment source446447**Note**: Requires Hevy connection. Returns error if user has no Hevy integration.448449### 16. Get Erg Results450451Get Concept2 ergometer results (rowing, skiing, biking).452453```454GET /api/v1/mcp/tools/get_erg_results?days={days}&machine_type={type}455```456457Parameters:458- `days` (optional): History period, 1-90, default 30459- `machine_type` (optional): Filter by machine — rower, skierg, bikerg460461Returns:462- `sessions`: List of erg sessions with detailed metrics463- `total_sessions`: Total session count464- `total_meters`: Total distance465- `total_time_seconds`: Total time on erg466- `avg_pace_formatted`: Overall average pace per 500m (e.g., "2:05.3")467- `machines`: Per-machine summary (session count, total meters, avg pace)468- `weekly_volume`: Weekly volume trend data469470Each session includes:471- `date`: Session date472- `machine_type`: rower, skierg, or bikerg473- `distance_meters`: Distance in meters474- `time_seconds`: Duration in seconds475- `pace_500m`: Pace per 500m formatted (e.g., "2:05.3")476- `calories`: Calories burned477- `stroke_rate`: Average strokes per minute478- `avg_hr`: Average heart rate (if available)479- `drag_factor`: Erg drag factor setting480481**Note**: Requires Concept2 connection. Returns error if user has no Concept2 integration.482483### 17. List Medications484485Get the user's prescription medications.486487```488GET /api/v1/mcp/tools/list_medications?active_only={true|false}489```490491Parameters:492- `active_only` (optional): Only show currently active medications, default true493494Returns:495- `medications`: List of medications with dosage, frequency, route, and reason496- `active_count`: Number of currently active medications497- `total_count`: Total medications tracked498499Each medication includes:500- `name`: Medication name (brand)501- `generic_name`: Generic/active ingredient name502- `dosage`: Dosage (e.g., "500mg")503- `frequency`: How often taken (e.g., "twice daily")504- `route`: Route of administration (oral, topical, injection, etc.)505- `is_active`: Currently taking506- `start_date` / `end_date`: When started/stopped507- `duration_days`: How long on this medication508- `reason`: Why prescribed (auto-decrypted from encrypted storage)509510### 18. Get Medical Profile511512Get the user's medical profile including conditions, allergies, family history, and health goals.513514```515GET /api/v1/mcp/tools/get_medical_profile516```517518Returns:519- `conditions`: List of medical conditions (active/managed)520- `allergies`: List of allergies with severity and reaction type521- `family_history`: Family medical history with relationships and onset ages522- `goals`: Active health goals with priorities and target dates523- `diet_type`: Current dietary pattern (if set)524- `condition_count` / `allergy_count`: Summary counts525526Each condition includes: `name`, `status` (active/managed/resolved/monitoring), `severity`, `diagnosed` date, `notes`527528Each allergy includes: `allergen`, `severity` (mild/moderate/severe/life_threatening), `reaction_type`529530Each family history item includes: `condition`, `relationship` (father/mother/etc.), `age_at_onset`, `notes`531532### 19. List Health Documents533534List all health documents including procedure reports, imaging, prescriptions, and more.535536```537GET /api/v1/mcp/tools/list_health_documents?limit={limit}&document_type={type}538```539540Parameters:541- `limit` (optional): Max documents to return, 1-50, default 20542- `document_type` (optional): Filter by type (lab_report, procedure_report, imaging, prescription, doctor_note, other)543544Returns:545- `documents`: List of health documents sorted by received date (newest first)546- `total_count`: Total documents for this user547- `by_type`: Breakdown of document counts by type548549Each document includes:550- `document_id`: Document ID551- `document_type`: Type (lab_report, procedure_report, imaging, etc.)552- `document_subtype`: Subtype (cac, dexa, colonoscopy, mammogram, etc.)553- `status`: Processing status (pending, processing, needs_review, extracted, archived)554- `filename`: Original filename555- `received_at`: When received (ISO format)556- `ai_summary`: AI-generated summary of the document557- `lab_name`: Lab name (for lab reports)558- `test_date`: Test/procedure date559560**Note**: This goes beyond `list_test_results` which only shows lab reports. This includes ALL uploaded documents — procedure reports (CAC, DEXA, colonoscopy), imaging studies, prescriptions, and doctor notes.561562## Interpreting Scores563564### Healthspan Score (0-100)565| Range | Status | Meaning |566|-------|--------|---------|567| 80-100 | OPTIMAL | Excellent health optimization |568| 65-79 | GOOD | Above average, minor improvements possible |569| 50-64 | SUBOPTIMAL | Room for improvement |570| <50 | NEEDS_ATTENTION | Several areas need focus |571572### Axis Scores573Each health dimension is scored independently:574- **Metabolic**: Blood sugar, insulin, lipids575- **Cardiovascular**: Heart health markers576- **Inflammatory**: hs-CRP, homocysteine577- **Hormonal**: Thyroid, testosterone, cortisol578- **Nutritional**: Vitamins, minerals579- **Liver/Kidney**: Organ function markers580581**Important**: It's possible to have a high overall score with one low axis score (or vice versa). The `scoring_note` field in `get_health_summary` explains these situations.582583### Biomarker Status Labels584| Label | Meaning |585|-------|---------|586| OPTIMAL | Within evidence-based ideal range |587| NORMAL | Within lab reference range |588| SUBOPTIMAL | Room for improvement |589| HIGH/LOW | Outside lab reference range |590| CRITICAL | Needs immediate medical attention |591592## Common Workflows593594### "How am I doing?"5951. Call `list_available_data` to see what's tracked5962. Call `get_health_summary` for the overall picture5973. Highlight top concerns and recent trends5984. If `scoring_note` is present, explain the score discordance599600### "Tell me about my vitamin D"6011. Call `query_biomarker?biomarker=vitamin d`6022. Present history, current status, and trend6033. Note optimal range vs current value604605### "What's my CRP?" / "How's my inflammation?"6061. Call `query_biomarker?biomarker=crp` (returns as "CRP" or "hs-CRP" depending on lab)6072. Present the value and trend6083. Explain what CRP measures (inflammation marker) - note if it's high-sensitivity609610### "How's my sleep/HRV?"6111. Call `get_wearable_stats?metric=sleep` or `?metric=hrv`6122. Show recent trends and averages6133. Compare to healthy baselines614615### "What should I focus on?"6161. Call `get_opportunities?limit=5`6172. Present top opportunities ranked by healthspan impact6183. Explain what each biomarker does and why optimizing it matters619620### "How old am I biologically?"6211. Call `get_biological_age`6222. If available, compare biological vs chronological age6233. Explain what age acceleration means6244. If not available, explain what tests are needed625626### "What supplements am I taking?"6271. Call `list_supplements?active_only=true`6282. List active supplements with dosages (use `dose_text` field)6293. Note duration on each supplement630631### "What workouts have I done?"6321. Call `get_activities?days=30`6332. Summarize total activity (duration, calories, distance)6343. List recent workouts with key metrics635636### "What should I do today?"6371. Call `get_today_actions?timezone=America/New_York` (use user's timezone if known)6382. Group actions by scheduled window (morning, afternoon, evening)6393. Show completion progress6404. Highlight uncompleted actions641642### "What should I focus on?" / "What are my health priorities?"6431. Call `get_protocol`6442. Present top priorities with current values and targets6453. Explain why each is prioritized6464. List key recommendations6475. Note protocol phase and days remaining648649### "What tests should I do next?" / "Am I due for any blood work?"6501. Call `get_upcoming_tests`6512. Highlight overdue tests first (urgent)6523. List tests due soon with timeframes6534. Mention AI-recommended tests for optimization6545. Note which biomarkers each panel covers655656### "Show me my lab reports" / "When was my last blood test?"6571. Call `list_test_results?limit=10`6582. Show reports with dates, lab names, and biomarker counts6593. Note the source (PDF upload, email, manual entry)660661### "Give me a full overview of all my biomarkers"6621. Call `list_all_biomarkers`6632. Group by category (metabolic, cardiovascular, etc.)6643. Highlight any critical or high/low values6654. Show status counts (e.g., "12 optimal, 3 suboptimal, 1 high")6665. Note trends (increasing/decreasing/stable)667668### "Show me my strength training" / "How's my lifting?"6691. Call `get_strength_training?days=30`6702. Summarize workout frequency and total volume6713. Show muscle group distribution (highlight any imbalances)6724. List recent workouts with top exercises673674### "Show me my rowing results" / "How are my erg sessions?"6751. Call `get_erg_results?days=30`6762. Summarize total sessions, distance, and average pace6773. Show per-machine breakdown if using multiple ergs6784. Highlight pace trends (improving/declining)679680### "What medications am I on?" / "What prescriptions do I take?"6811. Call `list_medications?active_only=true`6822. List active medications with dosage and frequency6833. Note route and reason if available6844. To see historical medications too, use `active_only=false`685686### "What are my medical conditions?" / "Do I have any allergies?"6871. Call `get_medical_profile`6882. Present conditions with status and severity6893. List allergies with severity levels6904. Show family history (relevant for risk assessment)6915. Note active health goals692693### "Show me all my health documents" / "What procedure reports do I have?"6941. Call `list_health_documents?limit=20`6952. Show type breakdown (lab reports, procedures, imaging, etc.)6963. List documents with AI summaries6974. Filter by type if user asks about specific category: `document_type=procedure_report`698699### "What should I read about?" / "Any health articles for me?"7001. Call `get_content_recommendations?limit=5`7012. Present articles with titles and relevance reasons7023. Explain why each is relevant to the user's biomarker profile703704## Example API Call705706```javascript707// Using web_fetch708web_fetch({709 url: "https://api.gevety.com/api/v1/mcp/tools/get_health_summary",710 method: "GET",711 headers: {712 "Authorization": "Bearer $GEVETY_API_TOKEN",713 "Content-Type": "application/json"714 }715})716```717718## Important Guidelines7197201. **Never diagnose** - Present data clearly but always suggest consulting healthcare providers for medical decisions7212. **Trends matter more than single values** - A slightly elevated reading improving over time is better than a normal reading that's declining7223. **Note data freshness** - Lab results may be weeks/months old; wearable data is typically daily7234. **Context is key** - Ask about supplements, medications, or lifestyle changes that might explain trends7245. **Privacy first** - Health data is sensitive; don't share or reference specific values outside this conversation725726## Error Handling727728| Error Code | Meaning | Action |729|------------|---------|--------|730| 401 | Invalid or expired token | User needs to regenerate token at gevety.com/settings |731| 404 + `did_you_mean` | Biomarker not found | Suggest alternatives from the response |732| 404 | No data found | User may not have uploaded labs yet |733| 429 | Rate limited | Wait a moment and retry |734735## Getting a Token736737Users can generate their API token at:738**https://gevety.com/settings** → Developer API → Generate Token739740The token format is `gvt_` followed by random characters.741742## Checking for Updates743744On first use each session, optionally check for updates:745746```747GET https://api.gevety.com/api/v1/mcp/tools/status748```749750No authentication required. If the request fails or times out, skip the check and proceed normally.751752Response (when successful):753```json754{755 "clawdbot_skill": { "latest": "1.8.0", "update_command": "clawdhub update gevety" },756 "announcement": "New feature available!"757}758```759760**If `clawdbot_skill.latest` > 1.8.0** (this skill's version), tell the user:761> "A Gevety skill update is available. Run: `clawdhub update gevety`"762763**If `announcement` is present**, mention it once per session.764765**If the status check fails**, don't mention it - just proceed with the user's request.766767To manually update:768```bash769clawdhub update gevety770```