API Documentation

Connect Your AI Agent

Gene2AI transforms your health data into structured, AI-ready JSON. Upload genomic data for SNP analysis, health documents (lab reports, checkup results, medical imaging) for AI-powered parsing, CGM data for time-series analysis, or record daily metrics manually. All data is accessible programmatically for your AI agents.

Quick Start

Step 1: Upload & Analyze

Upload genetic data (23andMe, AncestryDNA, WeGene), health documents (lab reports, checkup results, imaging reports), or CGM data (Sibionics xlsx) through the unified Upload button. Each data type is parsed into structured indicators.

Step 2: Generate an API Key

Generate a profile-scoped Bearer token from the API Keys page. Each key is bound to a specific health profile (e.g., yourself, a parent, a child). AI agents using this key can only access data for the bound profile.

Step 3: Query via API

Start with the Health Profile endpoint for a compact overview (~2-4KB), then drill down into specific categories as needed. Your AI agent gets structured health data instantly.

Data Tiers — Query Strategy

Gene2AI organizes health data into three tiers for efficient agent usage. Start with Tier 1 and drill down only when needed.

Tier 1: Health ProfileRecommended Start~2-4KB

Conclusions only — risk levels, metabolizer status, abnormal flags, medical findings summary. Safe to cache across sessions.

/health-data/profile

Tier 2: Detailed RecordsOn Demand~50-500KB

Specific genotypes, SNPs, lab values, cross-references, CGM time-series. Use per-session, do not persist.

/health-data/full, /risk-overview

Tier 3: Raw DataNot for AgentsMB+

Original genetic files, full analysis JSON, raw CGM readings. Never enters agent context.

Website only

Health Profile — Primary Endpoint

GEThttps://gene2.ai/api/v1/health-data/profile

Returns a compact, conclusions-only health profile (~2-4KB). This is the recommended first call for any agent session. Contains APOE genotype, CYP450 metabolizer status, HLA carrier status, elevated health risks, drug sensitivities, nutrition flags, abnormal lab indicators, ALL medical findings (imaging, physical exam, functional tests) grouped by category, and auto-generated suggested focus areas.

Cache-friendly: Contains no raw genetic data (no rs-IDs, no genotypes, no SNP details), so it is safe for agent memory and cross-session reference. Medical findings include ALL examination results (both normal and abnormal) with findings sorted by date (newest first). The finding field preserves the original language from the medical report.

bash

curl -s "https://gene2.ai/api/v1/health-data/profile" \
  -H "Authorization: Bearer $GENE2AI_API_KEY"

json

{
  "_format": "gene2ai-health-profile-v1",
  "dataCoverage": {
    "genomicMarkers": 324, "labIndicators": 247,
    "medicalFindings": 18, "cgmDays": 14
  },
  "genomicHighlights": {
    "apoe": "APOE ε3/ε4 — Increased (1 copy of ε4)",
    "cyp450": [
      { "gene": "CYP2D6", "status": "Normal Metabolizer",
        "affectedDrugs": [] }
    ],
    "elevatedRisks": [
      { "condition": "Alzheimer's Disease",
        "risk": "elevated", "note": "..." }
    ],
    "drugSensitivities": [
      { "drug": "Warfarin", "sensitivity": "increased" }
    ],
    "nutritionFlags": [
      { "nutrient": "Vitamin D", "note": "..." }
    ]
  },
  "abnormalIndicators": [
    { "name": "LDL Cholesterol", "value": 3.8,
      "unit": "mmol/L", "flag": "high" }
  ],
  "medicalFindings": {
    "imaging": [
      { "type": "imaging", "examType": "CT",
        "bodyPart": "Liver", "finding": "肝脏密度减低",
        "conclusion": "Mild fatty liver",
        "severity": "mild", "date": "2026-01-15" }
    ],
    "physical_exam": [...],
    "functional_test": [...]
  },
  "medicalFindingsSummary": {
    "total": 18, "abnormal": 4,
    "byCategory": { "imaging": { "total": 8, "abnormal": 3 }, ... }
  },
  "suggestedFocusAreas": [
    "Alzheimer's risk management (APOE ε4 carrier)", ...
  ]
}

Genomic Data API (Legacy)

Endpoint

GEThttps://gene2.ai/api/v1/genomics/:jobId

Note: The /health-data/full?category=genomic endpoint is preferred as it returns enriched, parsed data and supports filtering/grouping. This legacy endpoint is maintained for backward compatibility.

Authentication

Authorization: Bearer YOUR_API_KEY

API keys are JWT tokens valid for 30 days, each bound to a specific health profile. Generate them from your API Keys page.

cURL Example

bash

curl -X GET "https://gene2.ai/api/v1/genomics/YOUR_JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Genomic Data Categories

The genomic data is organized into 9 subcategories. When querying with ?category=genomic, each record includes a parsed data field with structured objects. Use ?format=grouped to get records organized by subcategory.

health_risk

193+ markers — Disease risk assessments (CFTR, Alzheimer's, CAD, T2D, etc.) grouped by condition/gene with SNP-level detail. Risk levels: low, average, slightly_elevated, elevated, high.

{
  "indicatorName": "Alzheimer's Disease",
  "indicatorCode": "alzheimers_disease_rs429358",
  "data": {
    "condition": "Alzheimer's Disease",
    "risk": "elevated", "confidence": "high",
    "description": "Variant associated with increased risk",
    "snps": ["rs429358"], "genotype": "CT"
  }
}

drug_response

61+ markers (PharmGKB + CPIC) — Pharmacogenomic predictions for Warfarin, Clopidogrel, SSRIs, Codeine, Tamoxifen with gene-level dosing recommendations

{
  "indicatorName": "Warfarin Sensitivity",
  "data": {
    "drug": "Warfarin", "gene": "VKORC1",
    "sensitivity": "increased",
    "recommendation": "Consider lower initial dose",
    "confidence": "high", "snps": ["rs9923231"]
  }
}

cyp450

CYP450 metabolizer phenotyping — CYP2C19/CYP2D6/CYP2C9 with CPIC star allele definitions and drug recommendations. Statuses: Ultrarapid, Normal, Intermediate, Poor Metabolizer.

{
  "indicatorName": "CYP2D6",
  "data": {
    "metabolizerStatus": "Normal Metabolizer",
    "activityScore": "2.0",
    "allele1": "*1", "allele2": "*2",
    "drugRecommendations": [
      { "drug": "Codeine",
        "recommendation": "Use label-recommended dosing",
        "evidence": "Strong (CPIC)" }
    ]
  }
}

hla

9 alleles — HLA allele typing via tag SNP inference for immune-related conditions and drug hypersensitivity (celiac, psoriasis, ankylosing spondylitis, SJS/TEN)

{
  "indicatorName": "HLA-B*57:01",
  "data": {
    "allele": "HLA-B*57:01",
    "carrierStatus": "Negative",
    "associations": [{
      "drug": "Abacavir",
      "name": "Abacavir Hypersensitivity",
      "evidence": "Strong (CPIC)"
    }]
  }
}

apoe

APOE genotyping — ε2/ε3/ε4 allele determination for Alzheimer's and cardiovascular risk

{
  "indicatorName": "APOE Genotype",
  "data": {
    "alleles": ["ε3", "ε4"],
    "alzheimerRisk": "Increased (1 copy of ε4)",
    "cardiovascularNote": "ε4 associated with higher LDL",
    "snps": {
      "rs429358": { "genotype": "CT" },
      "rs7412": { "genotype": "CC" }
    }
  }
}

trait

21+ markers — Hair color, skin pigmentation, caffeine metabolism, alcohol flush, lactose tolerance, muscle fiber type

{
  "indicatorName": "Caffeine Metabolism",
  "data": {
    "trait": "Caffeine Metabolism",
    "value": "fast_metabolizer",
    "gene": "CYP1A2", "confidence": 0.85
  }
}

nutrition

32+ markers — Vitamin D, Folate/MTHFR, B12, Omega-3, Iron, Calcium needs based on genetic variants

{
  "indicatorName": "Vitamin D",
  "data": {
    "nutrient": "Vitamin D", "need": "increased",
    "gene": "GC", "confidence": 0.85
  }
}

ancestry

Regional ancestry percentages from population-specific variant analysis

{
  "indicatorName": "East Asian",
  "data": { "region": "East Asian", "percentage": 95.2 }
}

Risk Overview & Cross-References

Comprehensive Risk Dashboard

GEThttps://gene2.ai/api/v1/health-data/risk-overview

Returns elevated genomic risks, abnormal lab values, and cross-references between lab indicators and genomic markers. Enables insights like "Your LDL is high AND you have genetic variants in LDLR associated with familial hypercholesterolemia."

python

response = requests.get(
    "https://gene2.ai/api/v1/health-data/risk-overview",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
overview = response.json()

# Cross-references: lab ↔ genomic
for ref in overview["crossReferences"]:
    lab = ref["labIndicator"]
    print(f"{lab['name']} ({lab['flag']}) → "
          f"{ref['relatedGenomicCount']} genomic markers")

Genomic Links for Lab Indicators

GEThttps://gene2.ai/api/v1/health-data/genomic-links/:code

Find genomic markers related to a specific lab indicator. Supported codes: TC, TG, LDL-C, HDL-C, SBP, DBP, FBG, HbA1c, BMI, UA, TSH, FT3, FT4, ALT, AST, GGT, ALP, TBIL, SCr, BUN, WBC, HGB, PLT, CRP

Lab-Genomic Summary

GEThttps://gene2.ai/api/v1/health-data/lab-genomic-summary

Returns all lab indicators with their related genomic record counts, for building cross-reference dashboards.

Error Handling

Status	Code	Description
401	missing_token	No Authorization header provided
401	invalid_token	The API key is malformed or invalid
403	token_expired	API key has expired (30-day limit)
403	key_revoked	API key was manually revoked
403	job_id_mismatch	Key not authorized for this job
404	job_not_found	The specified job does not exist
404	data_not_available	Analysis not yet complete

Health Data Vault API

Agent Upload & Query API

Gene2AI stores and manages all your health records — lab reports, checkup results, medical imaging, CGM time-series data, and self-reported metrics. These endpoints let your AI agent upload documents, submit structured data, and query your complete health profile.

Authentication & Profile Binding

All Health Data API endpoints use profile-scoped API keys (Bearer token). Generate one from the API Keys page.

How profile binding works:

Each API key is bound to one health profile at creation time. When you use this key, all queries automatically return data for the bound profile only. This prevents AI agents from accidentally mixing health data across family members.

To access multiple profiles, generate a separate key for each profile. The ?profileId= query parameter can override the key's default profile for advanced use cases.

Upload Health Document

POSThttps://gene2.ai/api/v1/health-data/upload

Upload a PDF or image of a health document. The system stores the file and triggers AI-powered parsing to extract structured indicators. For checkup reports containing medical imaging (B-ultrasound, CT, X-ray), the system automatically extracts imaging pages and creates separate imaging documents.

Form Fields

file PDF, image, or xlsx file (required)

category lab_result, checkup, medical_record, imaging, or cgm

title Document title (defaults to filename)

documentDate YYYY-MM-DD — date of the test/exam

source Channel identifier (openclaw, telegram, etc.)

profileId (optional) Profile ID — assign data to a specific family member profile

bash

curl -X POST "https://gene2.ai/api/v1/health-data/upload" \
  -H "Authorization: Bearer YOUR_HEALTH_API_KEY" \
  -F "file=@blood_test_report.pdf" \
  -F "category=lab_result" \
  -F "documentDate=2026-02-15" \
  -F "source=openclaw"

Auto-extraction: When uploading a checkup report (PDF), the system automatically detects pages containing medical imaging (B-ultrasound, CT, X-ray, MRI, ECG images) and creates separate imagingtype documents for each exam, with the extracted page image and matched text descriptions from the full report.

Query Document Status

GEThttps://gene2.ai/api/v1/health-data/doc/:id

Poll the parsing status of an uploaded document. When status is completed, the response includes all extracted health records with indicator names, values, units, reference ranges, and abnormal flags.

bash

curl "https://gene2.ai/api/v1/health-data/doc/DOC_ID" \
  -H "Authorization: Bearer YOUR_HEALTH_API_KEY"

Submit Structured Records

POSThttps://gene2.ai/api/v1/health-data/records

Submit structured health records directly — ideal for user-reported metrics like blood pressure, blood sugar, weight, or data extracted by the agent from conversation.

bash

curl -X POST "https://gene2.ai/api/v1/health-data/records" \
  -H "Authorization: Bearer YOUR_HEALTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "self_reported",
    "title": "Daily vitals - 2026-03-01",
    "documentDate": "2026-03-01",
    "source": "openclaw",
    "records": [
      {
        "indicatorName": "Systolic Blood Pressure",
        "indicatorNameZh": "收缩压",
        "valueNumeric": 125,
        "valueUnit": "mmHg",
        "refRangeLow": 90,
        "refRangeHigh": 140,
        "abnormalFlag": "normal"
      }
    ]
  }'

Query Health Data

GEThttps://gene2.ai/api/v1/health-data/profile

GEThttps://gene2.ai/api/v1/health-data/summary

GEThttps://gene2.ai/api/v1/health-data/full

GEThttps://gene2.ai/api/v1/health-data/delta?since_version=N

GEThttps://gene2.ai/api/v1/health-data/risk-overview

GEThttps://gene2.ai/api/v1/health-data/genomic-links/:code

GEThttps://gene2.ai/api/v1/health-data/lab-genomic-summary

GEThttps://gene2.ai/api/v1/health-data/export

profile — compact health profile (~2-4KB). Conclusions only. Recommended starting point. Supports ?profileId=.

summary — overview with document/record counts by category + genomic subcategory breakdown.

delta — incremental changes since a version number, for efficient sync.

risk-overview — comprehensive risk dashboard: elevated genomic risks, abnormal lab values, and cross-references.

genomic-links/:code — find genomic markers related to a lab indicator (e.g., LDL-C → cholesterol genes).

lab-genomic-summary — all lab indicators with related genomic record counts.

Multi-Profile Support (Family Health)

Manage health data for multiple family members under a single account. Create profiles for each person, then assign uploaded documents and records to specific profiles.

Profile Management Endpoints

GEThttps://gene2.ai/api/v1/health/profiles

POSThttps://gene2.ai/api/v1/health/profiles

PUThttps://gene2.ai/api/v1/health/profiles/:id

DELETEhttps://gene2.ai/api/v1/health/profiles/:id

bash

# Create a profile for a family member
curl -X POST "https://gene2.ai/api/v1/health/profiles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mom", "relationship": "mother", "gender": "female", "birthYear": 1965}'

# Query health data for a specific profile
curl "https://gene2.ai/api/v1/health-data/full?profileId=PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

CGM & Time-Series Data

Upload Continuous Glucose Monitor (CGM) data from Sibionics devices (.xlsx format). The system automatically calculates Time in Range (TIR), Glucose Management Indicator (GMI), average glucose, glucose variability, and daily trend analysis. CGM data is queryable via the standard endpoints.

bash

# Upload CGM data
curl -X POST "https://gene2.ai/api/v1/health-data/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@sibionics_export.xlsx" \
  -F "category=cgm" \
  -F "source=openclaw"

# Query CGM records
curl "https://gene2.ai/api/v1/health-data/full?category=cgm" \
  -H "Authorization: Bearer YOUR_API_KEY"

CGM indicators include: Average Glucose, Time in Range (TIR), Time Above Range, Time Below Range, GMI (estimated HbA1c), Glucose Variability (CV%), and per-day trend data with min/max/mean values.

Medical Imaging Auto-Extraction

When a checkup report PDF is uploaded, the system automatically scans each page for medical imaging content (B-ultrasound, CT, X-ray, MRI, ECG images). For each detected imaging exam with actual pictures:

The page image is extracted and uploaded to storage
A separate imaging type document is created automatically
Text descriptions are matched from the full report (cross-page matching)
Each imaging document is linked to its parent checkup report

Pure-text imaging findings (no actual picture on the page) remain in the original checkup report as findings. This means one checkup report can produce N+1 documents: 1 original report + N imaging documents.

OpenClaw Skill — Chat-based Upload

Install the Gene2AI Skill on your OpenClaw agent to upload health documents directly from Telegram, Feishu, or any connected chat platform. The skill also enables contextual health advisory, daily health briefings, and proactive health nudges — your AI agent becomes a health-aware companion.

View Skill File ·GitHub Repo

Contextual Health Advisory

The most powerful capability of Gene2AI: your AI agent acts as a health-aware layer, referencing the user's health profile when conversations touch health-adjacent topics.

How It Works

When the conversation touches medication, diet, exercise, sleep, or any health topic, the agent calls /health-data/profile and weaves relevant insights naturally into the response. The key principle: the response should be different from what a generic AI would say, because the agent knows this specific user's genetic and clinical background.

Medication

Check CYP450 status before discussing any drug. If poor metabolizer for CYP2D6: 'Codeine won't work well for you — your genetics mean you can't convert it to its active form.'

Diet & Nutrition

Cross-reference nutritionFlags with abnormalIndicators. If vitamin D flag + low lab value: 'Your genetics suggest reduced absorption, and your blood test confirms low levels.'

Exercise

Check muscle type traits, injury risk markers, and cardiovascular risk to tailor training recommendations.

Coffee & Caffeine

Check CYP1A2 status. Fast metabolizer: '2-3 cups may benefit cardiovascular health.' Slow: 'Keep it before noon.'

Daily Health Briefing

A bidirectional daily interaction: the agent summarizes the user's health status and encourages progress, then naturally prompts them to report a few easy-to-measure metrics. Everything is driven by the user's actual data — no fixed templates.

Briefing Content (Data-Driven)

Highlight 2-3 most relevant items from the health profile
Celebrate improvements (e.g., "Your BP has been consistently under 130 this week")
Gently flag worsening trends (e.g., "Fasting glucose creeping up")
Connect genetic risk to current data (e.g., "Given your APOE status, keeping LDL in check is especially important")

Check-in Prompt (Adaptive)

Ask for 1-2 metrics maximum per day, chosen based on the user's risk profile. Cardiovascular risk → blood pressure. Diabetes risk → fasting glucose. General wellness → rotate between weight, heart rate, sleep quality. Explain why you're asking in terms of their specific health profile.

See the SKILL.md Part 8 for complete implementation details including cron scheduling, decision logic, and privacy guidelines.

Re-analyze vs Refresh

Gene2AI continuously improves its analysis engine with expanded knowledge bases covering more SNP markers. Two options are available to update your results:

Refresh

Re-fetches your existing analysis results from the server. Useful if your data was partially imported or if you want to sync the latest parsed records.

Speed: Instant (seconds)

Result: Same analysis, re-imported

Re-analyze

Re-submits your original genomic file to the analysis engine for a completely fresh analysis using the latest knowledge base. This may significantly increase the number of analyzed indicators.

Speed: Minutes to hours

Result: New analysis with latest KB

Integration Tips

For ChatGPT / Claude

Paste the API endpoint and key into your system prompt. The AI can query your health data — genomics, lab results, medical imaging, CGM data — for personalized recommendations across medication, diet, exercise, and wellness topics.

For Custom Agents

Use the REST API in your agent's tool/function calling setup. Start with the Health Profile endpoint for a compact overview, then drill down as needed. The structured JSON format is designed for easy parsing by LLM-based agents.

For MCP Servers

Build an MCP tool that wraps the Gene2AI API. Your agent can then access genomic, clinical, and time-series health data as a native tool alongside other data sources.

Security Best Practices

Store API keys as environment variables, never in code. Keys expire after 30 days — generate new ones from the API Keys page. Revoke compromised keys immediately. Each key is bound to one profile, so a compromised key only exposes data for that profile.

Ready to Get Started?

Upload genetic data, health documents, or CGM data. Get structured AI-ready JSON. Start building personalized AI health experiences. Your health data vault grows richer with every upload.