Orviva API Guide — Connect Your AI Agent

Quick Start

Step 1 — Upload & Analyze: Upload genetic data (23andMe, AncestryDNA, WeGene), methylation β-value CSVs (Illumina 450k / EPIC / WeGene epigenetic), health documents (lab reports, checkup results, imaging reports), or CGM data (Sibionics xlsx). Each data type is parsed into structured indicators; methylation files are scored against 5 epigenetic clocks (Horvath / Hannum / PhenoAge / GrimAge / DunedinPACE), 2 methylation risk scores (AHRR smoking, Epi-CRP) and a 6-cell Houseman deconvolution via a pure Node.js math pipeline (no LLM).
Step 2 — Generate an API key: Create a profile-scoped Bearer token from the API Keys page, or call POST /api/auth/token with email + password to get a token directly. Each key can be labelled (e.g. 'iPhone', 'Claude Agent') for easy management.
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.

Machine-readable copies of this guide are always available regardless of User-Agent: this same document as Markdown at http://orviva.ai/guide.md, and a discovery index at http://orviva.ai/llms.txt. Agents can fetch either directly with no HTML/JS rendering required.

Data Tiers — Recommended Query Strategy

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

Tier	Name	Endpoint(s)	Size	Usage
Tier 1	Health Profile	/health-data/profile	~2-4KB	Conclusions only — risk levels, metabolizer status, abnormal flags, medical findings summary. Safe to cache across sessions. Recommended start.
Tier 2	Detailed Records	/health-data/full, /health-data/risk-overview	~50-500KB	Specific genotypes, SNPs, lab values, cross-references, CGM time-series. Use per-session, do not persist.
Tier 3	Raw Data	Website only	MB+	Original genetic files, full analysis JSON, raw CGM readings. Never enters agent context.

Health Profile API (Primary Endpoint)

`GET /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, an epigenetic block (latest methylation snapshot), 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 (normal and abnormal), sorted newest first. The `finding` field preserves the original language from the medical report. The `epigenetic` block is null when no methylation data is present.

curl -s "http://orviva.ai/api/v1/health-data/profile" \
  -H "Authorization: Bearer $ORVIVA_API_KEY"

{
  "_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": [ ... ], "physical_exam": [ ... ], "functional_test": [ ... ] },
  "medicalFindingsSummary": { "total": 18, "abnormal": 4, "byCategory": { ... } },
  "epigenetic": { "clocks": { ... }, "ageAccelerations": { ... }, "mrs": { ... }, "cellProportions": { ... }, "qc": { ... } },
  "suggestedFocusAreas": [ "Alzheimer's risk management (APOE ε4 carrier)", ... ]
}

Genomic Data API

`GET /api/v1/genomics/:jobId`

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

Authentication: API keys are JWT Bearer tokens valid for 30 days, each bound to a specific health profile. Generate them from the API Keys page, or call POST /api/auth/token to get a token programmatically with email + password.

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

Genomic Categories

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.

Subcategories

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.
drug_response: 61+ markers (PharmGKB + CPIC) — pharmacogenomic predictions for Warfarin, Clopidogrel, SSRIs, Codeine, Tamoxifen with gene-level dosing recommendations.
cyp450: CYP450 metabolizer phenotyping — CYP2C19/CYP2D6/CYP2C9 with CPIC star allele definitions and drug recommendations. Statuses: Ultrarapid, Normal, Intermediate, Poor Metabolizer.
hla: 9 alleles — HLA allele typing via tag SNP inference for immune-related conditions and drug hypersensitivity (celiac, psoriasis, ankylosing spondylitis, SJS/TEN).
apoe: APOE genotyping — ε2/ε3/ε4 allele determination for Alzheimer's and cardiovascular risk (rs429358, rs7412).
trait: 21+ markers — hair color, skin pigmentation, caffeine metabolism, alcohol flush, lactose tolerance, muscle fiber type.
nutrition: 32+ markers — Vitamin D, Folate/MTHFR, B12, Omega-3, Iron, Calcium needs based on genetic variants.
ancestry: Regional ancestry percentages from population-specific variant analysis.
meta: Analysis metadata — data source, total variants analyzed, API version, timestamp.

curl "http://orviva.ai/api/v1/health-data/full?category=genomic&subcategory=cyp450&format=grouped" \
  -H "Authorization: Bearer YOUR_API_KEY"

Methylation / Epigenetic Data

Upload a CSV of CpG β-values (probeId,beta columns, ~270k–860k rows from Illumina 450k / EPIC arrays or WeGene methylation exports). Orviva runs a pure Node.js math pipeline — no LLM — and returns clock ages, risk scores, immune cell composition and QC.

5 epigenetic clocks: Horvath, Hannum, PhenoAge, GrimAge, DunedinPACE (years / pace).
3 age accelerations: Horvath / PhenoAge / GrimAge age − chronological age (years).
2 methylation risk scores: AHRR smoking-exposure MRS, Epi-CRP chronic-inflammation predictor.
6-cell immune composition: CD4⁺ T, CD8⁺ T, NK, B, monocytes, granulocytes via Houseman NNLS reference deconvolution.
Multi-dimensional sample QC: probe-count gate (≥ 250K), β-value SD / intermediate-fraction distribution checks, Houseman residual, detection-p failure rate, predicted sex via X-chromosome panel with three-way cross-check against genomic chrY + self-reported sex.
3–6 plain-language findings linked to clinical indicators (CRP, APOE, TC, HBA1C, WBC) for cross-domain interpretation.

`POST /api/v1/health/documents/upload`

Upload the β-value CSV with category=methylation.

`GET /api/v1/health-data/full?category=methylation&format=grouped`

Retrieve derived indicators.

curl -X POST "http://orviva.ai/api/v1/health/documents/upload" \
  -H "Authorization: Bearer $ORVIVA_API_KEY" \
  -F "file=@methylation_beta_values.csv" \
  -F "category=methylation" \
  -F "title=Sep 2026 EPIC array"

Indicator codes produced: HORVATH_DNAM_AGE, HANNUM_DNAM_AGE, PHENOAGE, GRIMAGE, DUNEDINPACE, AGE_ACCEL_HORVATH / _PHENOAGE / _GRIM, METHYL_SMOKING_MRS, METHYL_CRP_MRS, METHYL_CD4T / _CD8T / _NK / _BCELL / _MONO / _GRAN, METHYL_DETECTION_FAIL_PCT, METHYL_SAMPLE_SEX_PRED. A compact snapshot is also embedded in /health-data/profile under the `epigenetic` key.

Methylation Samples (per-sample / compare)

Four dedicated endpoints let your agent inspect every methylation sample the user has uploaded and compare them longitudinally. All values come from the same Node.js math pipeline (no LLM).

`GET /api/v1/health-data/methylation/latest`

Most recent epigenetic snapshot — clocks, age accelerations, MRS, immune cell proportions, QC.

`GET /api/v1/health-data/methylation/samples`

List every methylation sample with documentId, sample date, parseStatus, clock count, indicator count.

`GET /api/v1/health-data/methylation/samples/:documentId`

One sample's full snapshot. Use ?cpgs=true to receive a pointer to the per-CpG endpoint.

`GET /api/v1/health-data/methylation/compare?a=DOC_A&b=DOC_B`

Per-clock and per-MRS deltas between two samples.

# Compare two methylation samples — newest vs baseline
curl "http://orviva.ai/api/v1/health-data/methylation/compare?a=DOC_NEW&b=DOC_BASELINE" \
  -H "Authorization: Bearer $ORVIVA_API_KEY"

Per-CpG β-values remain on GET /api/v1/health/methylation/indicator/:code?documentId=... — those payloads can run into tens of thousands of rows, so keep them out of agent memory and only fetch on demand. EpiScore codes (Gadd 2022) available on samples processed by the latest pipeline: METHYL_ADIPONECTIN_EPISCORE, METHYL_SHBG_EPISCORE, METHYL_MPO_EPISCORE, METHYL_MMP9_EPISCORE, METHYL_TNFRII_EPISCORE, METHYL_RESISTIN_EPISCORE, METHYL_VCAM1_EPISCORE, METHYL_B2M_EPISCORE.

Risk Overview & Cross-References

`GET /api/v1/health-data/risk-overview`

Elevated genomic risks, abnormal lab values, and cross-references between lab indicators and genomic markers.

`GET /api/v1/health-data/genomic-links/:code`

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.

Cross-references enable insights like: "Your LDL is high AND you have genetic variants in LDLR associated with familial hypercholesterolemia."

response = requests.get(
    "http://orviva.ai/api/v1/health-data/risk-overview",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
overview = response.json()
for ref in overview["crossReferences"]:
    lab = ref["labIndicator"]
    print(f"{lab['name']} ({lab['flag']}) -> {ref['relatedGenomicCount']} genomic markers")

Supplement Guidance (deterministic, no-LLM)

`GET /api/v1/health-data/supplement-guidance`

Runs the user's genomic markers, CYP450 metabolizer status, lab indicators, and elevated health risks through a deterministic nutrient knowledge base (gene → nutrient, CYP450 → supplement-interaction, risk → ingredient). No LLM call, so the output is reproducible and auditable — designed for partner APIs and agent function calling. Payload format: orviva-supplement-guidance-v1 (~5-15KB). Supports ?profileId=.

Payload shape

ingredientNeeds: Prioritized ingredient list (0-100), each with sources (gene/SNP, lab indicator, cross-ref), dose range, supporting ingredients, monitor indicators.
pathwayProfiles: Methylation, detox, lipid, etc. with status (impaired / partially impaired / normal) and affected genes.
supplementInteractions: CYP450-specific cautions (e.g. reduced-function CYP2C19 + St John's Wort).
riskNutrientMap: Elevated health risks paired with the ingredients that target them.
contraindications: Hard avoid list driven by genomic markers + active interventions.
matchingMetadata: Flat keyword arrays for product-catalog joins.

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

Orviva stores and manages all your health records — lab reports, checkup results, medical imaging, CGM time-series, and self-reported metrics. These endpoints let your AI agent upload documents, submit structured data, and query the complete health profile. All use profile-scoped API keys (Bearer token). Each key is bound to one health profile at creation time; the ?profileId= query parameter can override it for advanced use cases.

`POST /api/v1/health-data/upload`

Upload a PDF/image/xlsx. Form fields: file (required); category (lab_result, checkup, medical_record, imaging, methylation, cgm); title; documentDate (YYYY-MM-DD); source (openclaw, telegram, …); profileId (optional). Triggers AI parsing; checkup PDFs auto-extract imaging pages into separate imaging documents.

`GET /api/v1/health-data/doc/:id`

Poll parsing status. When status=completed the response includes extracted records with indicator names, values, units, reference ranges, and abnormal flags.

`POST /api/v1/health-data/records`

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

`GET /api/v1/health-data/profile`

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

`GET /api/v1/health-data/summary`

Overview with document/record counts by category + genomic subcategory breakdown.

`GET /api/v1/health-data/full`

`GET /api/v1/health-data/delta?since_version=N`

Incremental changes since a version number, for efficient sync.

`GET /api/v1/health-data/risk-overview`

Comprehensive risk dashboard with cross-references.

`GET /api/v1/health-data/genomic-links/:code`

Genomic markers related to a lab indicator (e.g. LDL-C → cholesterol genes).

`GET /api/v1/health-data/search?q=…`

Search across the user's health records. Params: ?q= (required), ?category=, ?page=, ?pageSize= (default 20).

`GET /api/v1/health-data/by-date?from=YYYY-MM-DD&to=YYYY-MM-DD`

One-shot fan-out across documents / records / findings / time-series for a date range. See Date-Range Query.

`GET /api/v1/health-data/supplement-guidance`

Deterministic ingredient-needs payload (no LLM).

`GET /api/v1/health-data/export`

Self-contained JSON with built-in AI instructions, cross-references, and trends. Params: ?scope=full|genomic|lab_checkup, ?anonymize=, ?includeRawRecords=, ?timeRange=all|1y|2y.

Multi-profile (family health): manage data for multiple family members under one account via GET/POST /api/v1/health/profiles and PUT/DELETE /api/v1/health/profiles/:id, then assign uploads and records to a specific profileId.

# Create a profile for a family member
curl -X POST "http://orviva.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}'

CGM & imaging: upload Sibionics CGM xlsx with category=cgm (TIR, GMI, average glucose, variability, daily trends are computed automatically). Checkup report PDFs auto-detect medical imaging pages (B-ultrasound, CT, X-ray, MRI, ECG) and create separate linked imaging documents — one report can produce N+1 documents.

Time-Series API (CGM and beyond)

Dedicated agent-facing surface for high-frequency time-series data (CGM today, more device types as the parser registry grows). Returns first-class stream objects with raw points, daily summaries, and period (TIR / GMI / variability) summaries. Each response carries a persistenceAdvice hint (tier, refreshInterval, description) so your agent can decide what to cache vs re-fetch.

`POST /api/v1/health-data/timeseries/upload`

Multipart upload (xlsx / xls / csv, ≤ 50MB). Detects device + data category, returns streamId + pollUrl while async processing runs.

`GET /api/v1/health-data/timeseries/streams`

List streams with period summary attached (TIR, GMI, mean glucose, CV%).

`GET /api/v1/health-data/timeseries/streams/:id`

One stream: device metadata, daily summaries, period summary. Use for stream detail polling.

`GET /api/v1/health-data/timeseries/daily?dataCategory=glucose`

Daily summaries across all of the user's streams for a given dataCategory (default: glucose).

# 1. Upload a Sibionics CGM export
curl -X POST "http://orviva.ai/api/v1/health-data/timeseries/upload" \
  -H "Authorization: Bearer $ORVIVA_API_KEY" \
  -F "file=@sibionics_cgm.xlsx" \
  -F "timezone=Asia/Shanghai"

# 2. Poll until status === "ready", then pull cross-stream daily glucose
curl "http://orviva.ai/api/v1/health-data/timeseries/daily?dataCategory=glucose" \
  -H "Authorization: Bearer $ORVIVA_API_KEY"

Date-Range Query (consolidated fan-out)

`GET /api/v1/health-data/by-date?from=YYYY-MM-DD&to=YYYY-MM-DD`

One call to answer "what happened in March?". Fans out across documents, records, findings, and (optionally) time-series daily summaries within [from, to]. Saves the agent from chaining 4+ separate requests and filtering client-side. Response carries top-level counts (documents, records, findings, per-category).

Query params

from: YYYY-MM-DD (required, inclusive).
to: YYYY-MM-DD (required, inclusive). Max span: 2 years.
date: YYYY-MM-DD shortcut — sets from = to = date.
categories: CSV: lab_result,checkup,imaging,methylation,cgm,…
includeTimeSeries: false to skip daily summaries (default: true).
pageSize: Per-table cap, default 200, max 1000.
profileId: Override the key's default profile.

Mobile & G2 Chat API

Access G2 (the built-in AI health assistant) from mobile apps or external clients. All chat endpoints support Bearer token authentication — the same tokens used for health data APIs.

`POST /api/auth/token`

Mobile login — get a Bearer token with email + password + optional label. No browser/cookie needed.

`POST /api/v1/chat/stream`

Send a message to G2, receive a streaming response via Server-Sent Events. Pass sessionId to continue a conversation. SSE events: session, token, tool_start, tool_result, done.

`GET /api/v1/chat/sessions`

List chat sessions.

`GET /api/v1/chat/sessions/:id/messages`

Get message history for a session.

`PUT /api/v1/chat/sessions/:id`

Rename a session.

`DELETE /api/v1/chat/sessions/:id`

Delete a session.

# Login and get a Bearer token
curl -X POST "http://orviva.ai/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your_password", "label": "My iPhone"}'

# Stream a chat message to G2
curl -N "http://orviva.ai/api/v1/chat/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are my recent lab results?"}'

API keys are created, relabelled and revoked from the API Keys page in the Orviva web UI (first-party, cookie-authenticated). By design there is no Bearer-authenticated key-management endpoint — a token cannot mint or revoke other tokens.

Contextual Health Advisory

The most powerful capability: your AI agent acts as a health-aware layer, referencing the user's health profile when conversations touch health-adjacent topics. 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 response should differ 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. Poor CYP2D6 metabolizer → "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. 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.
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. Highlight 2-3 most relevant profile items, celebrate improvements, gently flag worsening trends, and connect genetic risk to current data. Ask for 1-2 metrics maximum per day, chosen by the user's risk profile, and explain why in terms of their specific profile.

Interventions API (read + delete only)

Track medications, supplements, treatments, and anti-aging protocols the user is on, along with each recorded dose / session. This is a single-write-path domain by design: create / update / discontinue / record-event all happen through G2 chat tools so every change has a conversational audit trail. The REST surface exposes read + delete + a single not-duplicate override.

Auth model: the read and delete endpoints accept a Bearer API key carrying the matching health scope (health:read for reads, health:delete for deletes) or a first-party session cookie. There are no create/update REST endpoints by design — writes go through G2 chat so every change has a conversational audit trail. Send the user's message to POST /api/v1/chat/stream and G2's tools handle log_intervention_event, create_intervention, update_intervention, discontinue_intervention.

`GET /api/v1/interventions`

`GET /api/v1/interventions/:id`

One intervention detail.

`GET /api/v1/interventions/:id/events`

Events for one intervention. Params: ?startDate=, ?endDate=, ?limit= (max 500).

`GET /api/v1/interventions/timeline`

Cross-intervention event stream paginated by time.

`GET /api/v1/interventions/adherence?windowDays=7`

Per-intervention adherence summaries over the last N days.

`DELETE /api/v1/interventions/:id`

Delete an intervention (cascade-removes its events).

`DELETE /api/v1/intervention-events/:id`

Delete a single recorded event.

`PATCH /api/v1/intervention-events/:id/not-duplicate`

Clear the duplicate-warning flag on an event the user confirms is distinct.

Re-analyze vs Refresh

Refresh — re-fetches your existing analysis results from the server. Useful if data was partially imported or 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. 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 then query genomics, lab results, medical imaging and CGM data for personalized recommendations.
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. The structured JSON is designed for easy parsing by LLM-based agents.
For MCP Servers: build an MCP tool that wraps the Orviva API. Your agent accesses genomic, clinical, and time-series health data as a native tool.
Security: store API keys as environment variables, never in code. Keys expire after 30 days. Each key is bound to one profile, so a compromised key only exposes that profile. Revoke compromised keys immediately.