Helena Bioinformatics Browser API

openapi: 3.2.0
info:
  title: Helix Insight - Variant Analysis Service Browser API
  description: AI-powered variant analysis and interpretation service
  version: 0.1.0
tags:
- name: browser
paths:
  /sessions/{session_id}/browser/reference:
    get:
      tags:
      - browser
      summary: Bounded GRCh38 reference and MANE translation window
      description: 'Return the mounted GRCh38 bases and one overlapping MANE coding model.


        This is an authenticated, org-scoped and strictly bounded read-only surface.

        It is intentionally unavailable above base-level zoom so a pan cannot turn

        into an unbounded reference transfer.'
      operationId: get_browser_reference_sessions__session_id__browser_reference_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: chrom
        in: query
        required: true
        schema:
          type: string
          description: Chromosome (bare or chr-prefixed)
          title: Chrom
        description: Chromosome (bare or chr-prefixed)
      - name: start
        in: query
        required: true
        schema:
          type: integer
          minimum: 1
          description: 1-based inclusive window start
          title: Start
        description: 1-based inclusive window start
      - name: end
        in: query
        required: true
        schema:
          type: integer
          minimum: 1
          description: 1-based inclusive window end
          title: End
        description: 1-based inclusive window end
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserReferenceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/browser/region:
    get:
      tags:
      - browser
      summary: Region read for the genome browser
      description: All session features (snvs, svs, genes, regions) overlapping [start, end] on chrom.
      operationId: get_browser_region_sessions__session_id__browser_region_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: chrom
        in: query
        required: true
        schema:
          type: string
          description: Chromosome (bare or chr-prefixed)
          title: Chrom
        description: Chromosome (bare or chr-prefixed)
      - name: start
        in: query
        required: true
        schema:
          type: integer
          minimum: 0
          description: Window start (bp)
          title: Start
        description: Window start (bp)
      - name: end
        in: query
        required: true
        schema:
          type: integer
          minimum: 0
          description: Window end (bp)
          title: End
        description: Window end (bp)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserRegionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/browser/gene/{symbol}:
    get:
      tags:
      - browser
      summary: Look up a MANE gene by symbol (jump-to-gene for the browser search)
      description: 'Return the MANE coordinates for one gene symbol, anywhere in the genome.


        Org-scoped + READ-ONLY by construction (only a SELECT against the read-only

        reference_db singleton). Powers the search box''s jump-to-gene: the frontend

        calls this when a typed symbol is not among the genes in the loaded region.

        404 if the symbol is unknown to MANE.'
      operationId: get_browser_gene_sessions__session_id__browser_gene__symbol__get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: symbol
        in: path
        required: true
        schema:
          type: string
          title: Symbol
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserGeneOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/browser/variant-by-hgvs/{hgvs}:
    get:
      tags:
      - browser
      summary: Find a session variant by HGVS (jump-to-variant for the browser search)
      description: 'Return {chrom, pos} for a session variant identified by an HGVS string

        (genomic / cDNA / protein), regardless of the current zoom. Org-scoped +

        READ-ONLY (a single SELECT against the session variants table). 404 if no

        session variant matches the HGVS. The {hgvs:path} converter lets the value

        carry characters like ''>'' and '':'' without prior encoding concerns.'
      operationId: get_browser_variant_by_hgvs_sessions__session_id__browser_variant_by_hgvs__hgvs__get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: hgvs
        in: path
        required: true
        schema:
          type: string
          title: Hgvs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Browser Variant By Hgvs Sessions  Session Id  Browser Variant By Hgvs  Hgvs  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sessions/{session_id}/browser/overview:
    get:
      tags:
      - browser
      summary: Coarse whole-genome overview for the genome browser
      description: The once-per-session most-severe-first aggregate (snvs, svs, lead), capped at OVERVIEW_MAX_MARKERS.
      operationId: get_browser_overview_sessions__session_id__browser_overview_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserOverviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BrowserReferenceResponse:
      properties:
        chrom:
          type: string
          title: Chrom
        start:
          type: integer
          title: Start
        end:
          type: integer
          title: End
        sequence:
          type: string
          title: Sequence
        transcript:
          anyOf:
          - $ref: '#/components/schemas/BrowserReferenceTranscriptOut'
          - type: 'null'
      type: object
      required:
      - chrom
      - start
      - end
      - sequence
      title: BrowserReferenceResponse
    BrowserSvOut:
      properties:
        chrom:
          type: string
          title: Chrom
        start:
          type: integer
          title: Start
        end:
          type: integer
          title: End
        svType:
          anyOf:
          - type: string
          - type: 'null'
          title: Svtype
        cls:
          anyOf:
          - type: string
          - type: 'null'
          title: Cls
      type: object
      required:
      - chrom
      - start
      - end
      title: BrowserSvOut
      description: A structural variant span marker (frontend BrowserSv).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BrowserExonPextOut:
      properties:
        chrom:
          type: string
          title: Chrom
        gene:
          type: string
          title: Gene
        exonStart:
          type: integer
          title: Exonstart
        exonEnd:
          type: integer
          title: Exonend
        maxTissuePext:
          type: number
          title: Maxtissuepext
        meanPext:
          type: number
          title: Meanpext
        brainCortexPext:
          anyOf:
          - type: number
          - type: 'null'
          title: Braincortexpext
        wholeBloodPext:
          anyOf:
          - type: number
          - type: 'null'
          title: Wholebloodpext
        tier:
          type: string
          title: Tier
      type: object
      required:
      - chrom
      - gene
      - exonStart
      - exonEnd
      - maxTissuePext
      - meanPext
      - tier
      title: BrowserExonPextOut
      description: '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).'
    BrowserGeneOut:
      properties:
        chrom:
          type: string
          title: Chrom
        symbol:
          type: string
          title: Symbol
        start:
          type: integer
          title: Start
        end:
          type: integer
          title: End
        strand:
          anyOf:
          - type: string
          - type: 'null'
          title: Strand
        exons:
          items:
            type: integer
          type: array
          title: Exons
          default: []
      type: object
      required:
      - chrom
      - symbol
      - start
      - end
      title: BrowserGeneOut
      description: 'A gene model from MANE (frontend BrowserGene).


        MANE carries the CDS envelope (cds_start, cds_end), not a per-exon model,

        so exons is returned as an empty array (a recorded Section 6 limitation;

        the frontend Panel tolerates an empty exons array).'
    BrowserSnvOut:
      properties:
        chrom:
          type: string
          title: Chrom
        pos:
          type: integer
          title: Pos
        gene:
          anyOf:
          - type: string
          - type: 'null'
          title: Gene
        cls:
          anyOf:
          - type: string
          - type: 'null'
          title: Cls
        hgvs:
          anyOf:
          - type: string
          - type: 'null'
          title: Hgvs
        ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Ref
        alt:
          anyOf:
          - type: string
          - type: 'null'
          title: Alt
        bayesdelNoaf:
          anyOf:
          - type: number
          - type: 'null'
          title: Bayesdelnoaf
        bayesdelNoafPred:
          anyOf:
          - type: string
          - type: 'null'
          title: Bayesdelnoafpred
        spliceaiMax:
          anyOf:
          - type: number
          - type: 'null'
          title: Spliceaimax
        spliceaiPred:
          anyOf:
          - type: string
          - type: 'null'
          title: Spliceaipred
        phylop:
          anyOf:
          - type: number
          - type: 'null'
          title: Phylop
        gerp:
          anyOf:
          - type: number
          - type: 'null'
          title: Gerp
        alphamissense:
          anyOf:
          - type: number
          - type: 'null'
          title: Alphamissense
        sift:
          anyOf:
          - type: number
          - type: 'null'
          title: Sift
        metasvm:
          anyOf:
          - type: number
          - type: 'null'
          title: Metasvm
        dann:
          anyOf:
          - type: number
          - type: 'null'
          title: Dann
        mpc:
          anyOf:
          - type: number
          - type: 'null'
          title: Mpc
        af:
          anyOf:
          - type: number
          - type: 'null'
          title: Af
        afGrpmax:
          anyOf:
          - type: number
          - type: 'null'
          title: Afgrpmax
        popmax:
          anyOf:
          - type: string
          - type: 'null'
          title: Popmax
        hom:
          anyOf:
          - type: integer
          - type: 'null'
          title: Hom
        loeuf:
          anyOf:
          - type: number
          - type: 'null'
          title: Loeuf
        misZ:
          anyOf:
          - type: number
          - type: 'null'
          title: Misz
        pli:
          anyOf:
          - type: number
          - type: 'null'
          title: Pli
        clinvarSig:
          anyOf:
          - type: string
          - type: 'null'
          title: Clinvarsig
        reviewStars:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reviewstars
        clinvarId:
          anyOf:
          - type: string
          - type: 'null'
          title: Clinvarid
        criteria:
          anyOf:
          - type: string
          - type: 'null'
          title: Criteria
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        consequence:
          anyOf:
          - type: string
          - type: 'null'
          title: Consequence
        impact:
          anyOf:
          - type: string
          - type: 'null'
          title: Impact
        hgvsCdna:
          anyOf:
          - type: string
          - type: 'null'
          title: Hgvscdna
        transcriptId:
          anyOf:
          - type: string
          - type: 'null'
          title: Transcriptid
        transcriptRepresentations:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Transcriptrepresentations
        exonNumber:
          anyOf:
          - type: string
          - type: 'null'
          title: Exonnumber
        domains:
          anyOf:
          - type: string
          - type: 'null'
          title: Domains
        pm1Source:
          anyOf:
          - type: string
          - type: 'null'
          title: Pm1Source
        vcepApplied:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Vcepapplied
        vcepPanel:
          anyOf:
          - type: string
          - type: 'null'
          title: Vceppanel
        deNovo:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Denovo
        hiScore:
          anyOf:
          - type: integer
          - type: 'null'
          title: Hiscore
        tsScore:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tsscore
      type: object
      required:
      - chrom
      - pos
      title: BrowserSnvOut
      description: '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.'
    BrowserRegionOut:
      properties:
        chrom:
          type: string
          title: Chrom
        start:
          type: integer
          title: Start
        end:
          type: integer
          title: End
        axis:
          type: string
          title: Axis
        iscaId:
          anyOf:
          - type: string
          - type: 'null'
          title: Iscaid
        score:
          anyOf:
          - type: integer
          - type: 'null'
          title: Score
      type: object
      required:
      - chrom
      - start
      - end
      - axis
      title: BrowserRegionOut
      description: A ClinGen dosage region marker on one axis (frontend BrowserRegion).
    BrowserReferenceTranscriptOut:
      properties:
        geneSymbol:
          type: string
          title: Genesymbol
        transcriptId:
          type: string
          title: Transcriptid
        proteinId:
          anyOf:
          - type: string
          - type: 'null'
          title: Proteinid
        strand:
          type: string
          title: Strand
        exons:
          items:
            items:
              type: integer
            type: array
          type: array
          title: Exons
        cds:
          items:
            items:
              type: integer
            type: array
          type: array
          title: Cds
        codons:
          items:
            $ref: '#/components/schemas/BrowserReferenceCodonOut'
          type: array
          title: Codons
      type: object
      required:
      - geneSymbol
      - transcriptId
      - strand
      title: BrowserReferenceTranscriptOut
    BrowserReferenceCodonOut:
      properties:
        bases:
          type: string
          title: Bases
        aminoAcid:
          type: string
          title: Aminoacid
        proteinPosition:
          type: integer
          title: Proteinposition
        genomicPositions:
          items:
            type: integer
          type: array
          title: Genomicpositions
      type: object
      required:
      - bases
      - aminoAcid
      - proteinPosition
      - genomicPositions
      title: BrowserReferenceCodonOut
    BrowserRegionResponse:
      properties:
        snvs:
          items:
            $ref: '#/components/schemas/BrowserSnvOut'
          type: array
          title: Snvs
        svs:
          items:
            $ref: '#/components/schemas/BrowserSvOut'
          type: array
          title: Svs
        genes:
          items:
            $ref: '#/components/schemas/BrowserGeneOut'
          type: array
          title: Genes
        regions:
          items:
            $ref: '#/components/schemas/BrowserRegionOut'
          type: array
          title: Regions
        pext:
          items:
            $ref: '#/components/schemas/BrowserExonPextOut'
          type: array
          title: Pext
          default: []
      type: object
      required:
      - snvs
      - svs
      - genes
      - regions
      title: BrowserRegionResponse
      description: The region read payload (frontend getBrowserRegion result).
    BrowserLeadOut:
      properties:
        chrom:
          type: string
          title: Chrom
        pos:
          type: integer
          title: Pos
      type: object
      required:
      - chrom
      - pos
      title: BrowserLeadOut
      description: The most-severe feature locus for the initial-view frame.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BrowserOverviewResponse:
      properties:
        snvs:
          items:
            $ref: '#/components/schemas/BrowserSnvOut'
          type: array
          title: Snvs
        svs:
          items:
            $ref: '#/components/schemas/BrowserSvOut'
          type: array
          title: Svs
        lead:
          anyOf:
          - $ref: '#/components/schemas/BrowserLeadOut'
          - type: 'null'
      type: object
      required:
      - snvs
      - svs
      title: BrowserOverviewResponse
      description: The coarse whole-genome aggregate (frontend BrowserGenomeOverview).
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer