--- title: "Pangenome graph view for a locus window" method: GET path: "/sessions/{session_id}/graph" tags: ["graph"] --- # Pangenome graph view for a locus window `GET /sessions/{session_id}/graph` ## Request - Base URL: `https://api.helena.bio` (the document declares no server; this is the origin it was published from) - URL: `https://api.helena.bio/sessions/{session_id}/graph` - Auth: HTTP bearer The T3 compact-JSON pangenome graph (nodes, edges, paths, bubbles, meta) for [start, end] on chrom, serialized by_alias so edges emit {from, to}. ## Path parameters - `session_id` string, uuid, required ## Query parameters - `chrom` string, required: Chromosome (bare or chr-prefixed) - `start` integer, required: Window start (bp) - `end` integer, required: Window end (bp) ## Response `200` Successful Response - PangenomeGraphResponse: The top-level compact-JSON pangenome graph response. The single wire contract assembled by the serializer (T8) and served by the endpoint (T9) as a response_model. The pipeline tasks (T4-T7) produce the nodes / edges / paths / bubbles; T8 attaches each bubble's evidence and sets meta; T9 serves it with by_alias=True so the edge from/to and the camelCase fields reach the wire (CR Section 5 I1). - `nodes` PangenomeNode[], required - `id` string, required - `x` number, required - `y` number, required - `label` string, required - `kind` string, required - `length` integer, required - `bubbleId` string, nullable - `edges` PangenomeEdge[], required - `from` string, required - `to` string, required - `paths` PangenomePath[], required - `id` string, required - `name` string, required - `route` string[], required - `bold` boolean - `bubbles` PangenomeBubble[], required - `id` string, required - `position` integer, required - `alleles` string[], required - `evidence` PangenomeBubbleEvidence: The bubble evidence SLOT -- the clinical-critical reuse of the shared linear-view evidence shape. It REUSES the SAME models the linear browser serves (BrowserSnvOut: the five established fields + 35 additive evidence fields; BrowserExonPextOut: the per-exon pext lane incl. the server-derived tier), imported from infrastructure.browser_evidence. There is NO second, graph-specific evidence shape: a bubble carries the SAME evidence the linear view serves so a clinician sees identical evidence in both views and the graph view never recomputes a verdict (CR Section 2.5). The serializer (T8) POPULATES this slot from the same classifier evidence the linear view reads (CR I3); T3 owns only the SHAPE. - `snv` BrowserSnvOut: A small variant marker (frontend BrowserSnv). CR-2026-BROWSER-EVIDENCE-TRACKS-001-P1 (Wave 1, Phase 1): the five established fields (chrom, pos, gene, cls, hgvs) are UNCHANGED. Below them 35 ADDITIVE per-variant evidence fields are appended, ALL Optional with a None default (a pure additive contract widening -- an old frontend ignores the unknown keys, a new frontend can be built against the widened contract). Each field is read from the per-session `variants` table; a session whose table lacks a source column degrades to None via _evidence_columns_present (the schema-drift guard), so every field is genuinely optional. Wire names are camelCase (matching the existing svType / iscaId convention). The wire-name -> `variants` source-column mapping is CR Section 3a; the per-field types follow the source column types in variant_schema.py (re-verified 2026-06-20, Eunomia B1). CRITICAL (Eunomia B1): exonNumber and popmax are Optional[str] -- exon_number is VARCHAR(20) carrying the VEP "X/Y" form (e.g. "3/12"), popmax is VARCHAR(10) carrying a population LABEL, NOT a number; typing either as int would raise a Pydantic ValidationError -> 500 on a real coding-gene window, which the frontend degrade-clean handler masks as a silently-empty browser. - `chrom` string, required - `pos` integer, required - `gene` string, nullable - `cls` string, nullable - `hgvs` string, nullable - `ref` string, nullable - `alt` string, nullable - `bayesdelNoaf` number, nullable - `bayesdelNoafPred` string, nullable - `spliceaiMax` number, nullable - `spliceaiPred` string, nullable - `phylop` number, nullable - `gerp` number, nullable - `alphamissense` number, nullable - `sift` number, nullable - `metasvm` number, nullable - `dann` number, nullable - `mpc` number, nullable - `af` number, nullable - `afGrpmax` number, nullable - `popmax` string, nullable - `hom` integer, nullable - `loeuf` number, nullable - `misZ` number, nullable - `pli` number, nullable - `clinvarSig` string, nullable - `reviewStars` integer, nullable - `clinvarId` string, nullable - `criteria` string, nullable - `confidence` number, nullable - `consequence` string, nullable - `impact` string, nullable - `hgvsCdna` string, nullable - `transcriptId` string, nullable - `transcriptRepresentations` object, nullable - `exonNumber` string, nullable - `domains` string, nullable - `pm1Source` string, nullable - `vcepApplied` boolean, nullable - `vcepPanel` string, nullable - `deNovo` boolean, nullable - `hiScore` integer, nullable - `tsScore` integer, nullable - `pext` BrowserExonPextOut: A per-exon pext marker (frontend BrowserExonPext). CR-2026-BROWSER-EVIDENCE-TRACKS-001-P2 (Wave 1, Phase 2): a NEW pext-lane source read from the read-only reference_db table exon_pext (gnomAD v4.1 / GTEx v10 per-exon expression proportion). Wire names are camelCase (the existing svType / iscaId convention). The per-field types follow EXON_PEXT_ DDL (registry/exon_pext.py): chromosome / gene_symbol VARCHAR -> str; exon_start / exon_end BIGINT -> int; max_tissue_pext / mean_pext FLOAT NOT NULL -> float; brain_cortex_pext / whole_blood_pext FLOAT nullable -> Optional[float]. tier is DERIVED server-side from maxTissuePext via _pext_tier using the classifier's exact PVS1 cut (acmg_classifier.py L5155-5160): one of 'full' | 'downgrade' | 'block' (CR Section 2.3). - `chrom` string, required - `gene` string, required - `exonStart` integer, required - `exonEnd` integer, required - `maxTissuePext` number, required - `meanPext` number, required - `brainCortexPext` number, nullable - `wholeBloodPext` number, nullable - `tier` string, required - `privateVariants` PangenomePrivateVariant[] - `position` integer, required - `gene` string, nullable - `acmgClass` string, nullable - `evidence` PangenomeBubbleEvidence: The bubble evidence SLOT -- the clinical-critical reuse of the shared linear-view evidence shape. It REUSES the SAME models the linear browser serves (BrowserSnvOut: the five established fields + 35 additive evidence fields; BrowserExonPextOut: the per-exon pext lane incl. the server-derived tier), imported from infrastructure.browser_evidence. There is NO second, graph-specific evidence shape: a bubble carries the SAME evidence the linear view serves so a clinician sees identical evidence in both views and the graph view never recomputes a verdict (CR Section 2.5). The serializer (T8) POPULATES this slot from the same classifier evidence the linear view reads (CR I3); T3 owns only the SHAPE. - `snv` BrowserSnvOut: A small variant marker (frontend BrowserSnv). CR-2026-BROWSER-EVIDENCE-TRACKS-001-P1 (Wave 1, Phase 1): the five established fields (chrom, pos, gene, cls, hgvs) are UNCHANGED. Below them 35 ADDITIVE per-variant evidence fields are appended, ALL Optional with a None default (a pure additive contract widening -- an old frontend ignores the unknown keys, a new frontend can be built against the widened contract). Each field is read from the per-session `variants` table; a session whose table lacks a source column degrades to None via _evidence_columns_present (the schema-drift guard), so every field is genuinely optional. Wire names are camelCase (matching the existing svType / iscaId convention). The wire-name -> `variants` source-column mapping is CR Section 3a; the per-field types follow the source column types in variant_schema.py (re-verified 2026-06-20, Eunomia B1). CRITICAL (Eunomia B1): exonNumber and popmax are Optional[str] -- exon_number is VARCHAR(20) carrying the VEP "X/Y" form (e.g. "3/12"), popmax is VARCHAR(10) carrying a population LABEL, NOT a number; typing either as int would raise a Pydantic ValidationError -> 500 on a real coding-gene window, which the frontend degrade-clean handler masks as a silently-empty browser. - `chrom` string, required - `pos` integer, required - `gene` string, nullable - `cls` string, nullable - `hgvs` string, nullable - `ref` string, nullable - `alt` string, nullable - `bayesdelNoaf` number, nullable - `bayesdelNoafPred` string, nullable - `spliceaiMax` number, nullable - `spliceaiPred` string, nullable - `phylop` number, nullable - `gerp` number, nullable - `alphamissense` number, nullable - `sift` number, nullable - `metasvm` number, nullable - `dann` number, nullable - `mpc` number, nullable - `af` number, nullable - `afGrpmax` number, nullable - `popmax` string, nullable - `hom` integer, nullable - `loeuf` number, nullable - `misZ` number, nullable - `pli` number, nullable - `clinvarSig` string, nullable - `reviewStars` integer, nullable - `clinvarId` string, nullable - `criteria` string, nullable - `confidence` number, nullable - `consequence` string, nullable - `impact` string, nullable - `hgvsCdna` string, nullable - `transcriptId` string, nullable - `transcriptRepresentations` object, nullable - `exonNumber` string, nullable - `domains` string, nullable - `pm1Source` string, nullable - `vcepApplied` boolean, nullable - `vcepPanel` string, nullable - `deNovo` boolean, nullable - `hiScore` integer, nullable - `tsScore` integer, nullable - `pext` BrowserExonPextOut: A per-exon pext marker (frontend BrowserExonPext). CR-2026-BROWSER-EVIDENCE-TRACKS-001-P2 (Wave 1, Phase 2): a NEW pext-lane source read from the read-only reference_db table exon_pext (gnomAD v4.1 / GTEx v10 per-exon expression proportion). Wire names are camelCase (the existing svType / iscaId convention). The per-field types follow EXON_PEXT_ DDL (registry/exon_pext.py): chromosome / gene_symbol VARCHAR -> str; exon_start / exon_end BIGINT -> int; max_tissue_pext / mean_pext FLOAT NOT NULL -> float; brain_cortex_pext / whole_blood_pext FLOAT nullable -> Optional[float]. tier is DERIVED server-side from maxTissuePext via _pext_tier using the classifier's exact PVS1 cut (acmg_classifier.py L5155-5160): one of 'full' | 'downgrade' | 'block' (CR Section 2.3). - `chrom` string, required - `gene` string, required - `exonStart` integer, required - `exonEnd` integer, required - `maxTissuePext` number, required - `meanPext` number, required - `brainCortexPext` number, nullable - `wholeBloodPext` number, nullable - `tier` string, required - `meta` PangenomeMeta, required: The response metadata. coordinateSystem defaults to PANGENOME_COORDINATE_SYSTEM (the linear-browser basis, declared on the wire so the two views share selection). inferredPhasing is the phasing-honesty flag: True when the patient route is an INFERRED route (an unphased case threaded as if it had a single route), False when the route derives from real phasing (VCF PS tags). Default True is the conservative, honest default -- an unset flag must not assert real phasing; T6 owns flipping it to False only when phasing is real (CR Section 2.3, AC-4). coordinateSystem / inferredPhasing are camelCase identifiers (no keyword clash, valid Python names), so they need no alias. - `locus` string, required - `coordinateSystem` string - `inferredPhasing` boolean ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/helena/apis/helix-insight-variant-analysis-service.md) · [All operations](https://skmtc.dev/helena/apis/helix-insight-variant-analysis-service/llms.txt) · [OpenAPI document](https://skmtc.dev/helena/apis/helix-insight-variant-analysis-service/revisions/fe51fd20cdf1?raw)