GenoMatrix™ API 文档

16 个标准化端点 · RESTful 设计 · 完整马属基因组学数据接口

🔗 Base URL: https://api.genomatrix.ai/v1

📡 系统端点

GET / 系统根信息

返回 API 版本、服务状态、可用端点列表等系统元信息。

Response 200
{
  "service": "GenoMatrix EQAI OS",
  "version": "2.0.0",
  "status": "online",
  "database": "full",
  "endpoints": 16,
  "genes_loaded": 41896,
  "variants_loaded": 40150000
}

GET /api/v1/status 系统运行状态

返回系统运行状态、数据库连接状态、内存使用等信息。

Response 200
{
  "status": "operational",
  "uptime": "45d 12h 33m",
  "database": { "status": "connected", "tables": 982 },
  "memory": { "used": "14.2 GB", "total": "32 GB" }
}

GET /health 健康检查

轻量级健康检查端点，用于负载均衡器和监控系统。

Response 200
{ "status": "healthy", "timestamp": "2026-07-09T14:30:00Z" }

🧬 基因查询

GET /api/v1/genes 列出所有基因

返回系统中所有可用基因列表。支持分页和搜索过滤。

Query Parameters

参数	类型	必填	说明
`page`	integer	否	页码，默认 1
`limit`	integer	否	每页数量，默认 50，最大 200
`search`	string	否	按基因名称搜索
`chromosome`	string	否	按染色体过滤，如 chr1, chrX

Response 200
{
  "total": 41896,
  "page": 1,
  "data": [
    {
      "gene": "MSTN",
      "name": "Myostatin",
      "chromosome": "chr1",
      "start": 66446558,
      "end": 66451558,
      "biotype": "protein_coding",
      "variants_count": 1247
    }
  ]
}

GET /api/v1/gene/{symbol} 查询单个基因详情

返回指定基因的完整信息，包括坐标、功能注释、相关变异、因果证据等。

Path Parameters

参数	类型	说明
`symbol`	string	基因符号，如 MSTN, DMRT3, BDNF

Response 200 — MSTN 示例
{
  "gene": "MSTN",
  "name": "Myostatin",
  "chromosome": "chr1",
  "start": 66446558,
  "end": 66451558,
  "strand": "+",
  "biotype": "protein_coding",
  "description": "肌肉生长抑制因子，调控肌肉发育",
  "causal_variants": 23,
  "ncds_tier": "A",
  "sport_association": ["sprint", "endurance"]
}

GET /api/v1/gene/{symbol}/variants 基因相关变异位点

返回指定基因区域内的所有变异位点，包括 VEP 注释和 SIFT/PolyPhen 预测。

Query Parameters

参数	类型	说明
`consequence`	string	按效应过滤：missense, synonymous, stop_gained 等
`sift`	string	SIFT 预测：tolerated, deleterious
`polyphen`	string	PolyPhen 预测：benign, possibly_damaging, probably_damaging

Response 200
{
  "gene": "MSTN",
  "total_variants": 1247,
  "data": [
    {
      "rsid": "rs1234567",
      "chrom": "chr1",
      "pos": 66448234,
      "ref": "C",
      "alt": "T",
      "consequence": "missense_variant",
      "sift": "deleterious",
      "polyphen": "probably_damaging",
      "causal_tier": "A"
    }
  ]
}

🛡️ JumpHealth 遗传病筛查

GET /api/v1/jumphealth/breeds 支持品种列表

返回 JumpHealth 系统支持的所有马品种及其预置疾病面板。

Response 200
{
  "total_breeds": 400,
  "data": [
    { "breed": "Thoroughbred", "panel_size": 12 },
    { "breed": "Quarter Horse", "panel_size": 10 },
    { "breed": "Mongolian", "panel_size": 8 }
  ]
}

POST /api/v1/jumphealth/report 生成遗传病筛查报告

基于品种和基因型数据，生成 JumpHealth 遗传病风险评估报告。

Request Body (JSON)

字段	类型	必填	说明
`breed`	string	是	品种名称
`genotype`	object	否	基因型数据 (rsid: allele)

Request
{ "breed": "Quarter Horse" }

Response 200
{
  "report_id": "JH-2026-070901",
  "breed": "Quarter Horse",
  "diseases_screened": 10,
  "results": [
    {
      "disease": "HYPP",
      "gene": "SCN4A",
      "status": "Clear",
      "risk_level": "low"
    },
    {
      "disease": "PSSM1",
      "gene": "GYS1",
      "status": "Carrier",
      "risk_level": "moderate"
    }
  ]
}

GET /api/v1/jumphealth/diseases 疾病面板列表

返回所有可筛查的遗传性疾病列表及其关联基因。

Response 200
{
  "total": 12,
  "data": [
    { "disease": "HYPP", "gene": "SCN4A", "inheritance": "autosomal_dominant" },
    { "disease": "PSSM1", "gene": "GYS1", "inheritance": "autosomal_dominant" },
    { "disease": "HERDA", "gene": "PPIB", "inheritance": "autosomal_recessive" },
    { "disease": "GBED", "gene": "GYG1", "inheritance": "autosomal_recessive" },
    { "disease": "MH", "gene": "RYR1", "inheritance": "autosomal_dominant" }
  ]
}

🧠 NCDS 模型

GET /api/v1/ncds/summary NCDS v3.4 模型摘要

返回 NCDS v3.4 模型（Neuro-Centric Differentiable System）的完整架构信息。

Response 200
{
  "model": "NCDS",
  "version": "3.4",
  "full_name": "Neuro-Centric Differentiable System",
  "total_genes": 102,
  "modules": {
    "neuro": { "genes": 34, "function": "神经调控与信号传导" },
    "skeletal": { "genes": 38, "function": "骨骼发育与肌肉功能" },
    "developmental": { "genes": 30, "function": "生长发育与代谢调控" }
  },
  "validation_rate": 0.90,
  "sport_engines": 7
}

GET /api/v1/ncds/genes NCDS 功能基因列表

返回 NCDS 模型中 102 个功能基因的完整列表，含模块归属和功能注释。

Response 200
{
  "total": 102,
  "data": [
    {
      "gene": "MSTN",
      "module": "skeletal",
      "tier": "A",
      "role": "肌肉生长负调控因子",
      "validated": true
    }
  ]
}

🏇 品种与运动

GET /api/v1/breeds 品种数据概览

返回中国马品种基因数据概览，包含品种列表和等位基因频率统计。

Response 200
{
  "total_breeds": 400,
  "chinese_breeds": 89,
  "chinese_native": 29,
  "data": [
    { "breed": "蒙古马", "samples": 342, "variants": 38500000 },
    { "breed": "伊犁马", "samples": 218, "variants": 37200000 }
  ]
}

GET /api/v1/sport/profile 运动适性评估

基于 NCDS 模型的运动适性分类与性能预测。

Query Parameters

参数	类型	说明
`breed`	string	品种名称

Response 200
{
  "breed": "Thoroughbred",
  "sport_scores": {
    "sprint": 0.87,
    "endurance": 0.62,
    "dressage": 0.58,
    "jumping": 0.71,
    "racing": 0.92
  }
}

GET /api/v1/knowledge-graph 知识图谱数据

返回基因调控网络的知识图谱数据，含节点和边信息。

Response 200
{
  "nodes": 5178,
  "edges": 125342,
  "edge_types": ["ACTIVATE", "INHIBIT", "MODULATE"],
  "data": { "nodes": [...], "links": [...] }
}

🔬 高级端点

GET /api/v1/causal-edges 因果调控边查询

查询基因间因果调控关系，支持按方向、强度、证据来源过滤。

Query Parameters

参数	类型	说明
`source`	string	上游基因
`target`	string	下游基因
`type`	string	调控类型: ACTIVATE / INHIBIT / MODULATE
`min_score`	float	最小置信度分数 (0-1)

Response 200
{
  "total": 125342,
  "data": [
    {
      "source": "MSTN",
      "target": "ACTN3",
      "type": "INHIBIT",
      "score": 0.94,
      "evidence": "experimental"
    }
  ]
}

GET /api/v1/structural-variants 结构变异查询

查询马属结构变异数据，支持 DEL / INS / INV / DUP / CNV 五大类型。

Query Parameters

参数	类型	说明
`type`	string	变异类型: DEL / INS / INV / DUP / CNV
`chromosome`	string	染色体
`min_size`	integer	最小变异长度 (bp)

Response 200
{
  "total": 28543,
  "types": { "DEL": 12045, "INS": 8721, "INV": 3412, "DUP": 2891, "CNV": 1474 },
  "data": [
    {
      "sv_id": "SV_00001",
      "type": "DEL",
      "chrom": "chr1",
      "start": 66446000,
      "end": 66452000,
      "size": 6000,
      "overlaps_gene": "MSTN"
    }
  ]
}

GET /api/v1/breed-frequency 品种等位基因频率

查询特定位点在不同品种中的等位基因频率分布。

Query Parameters

参数	类型	说明
`rsid`	string	变异位点 rsID
`breed`	string	品种名称（可选，不传返回所有品种）

Response 200
{
  "rsid": "rs1234567",
  "data": [
    { "breed": "Thoroughbred", "alt_freq": 0.73, "n": 512 },
    { "breed": "Arabian", "alt_freq": 0.45, "n": 328 },
    { "breed": "蒙古马", "alt_freq": 0.31, "n": 342 }
  ]
}