Helena Bioinformatics Families API

openapi: 3.2.0
info:
  title: Helix Insight - Variant Analysis Service Families API
  description: AI-powered variant analysis and interpretation service
  version: 0.1.0
tags:
- name: families
paths:
  /api/v1/vcf/validate-multisample:
    post:
      tags:
      - families
      summary: Parse multi-sample VCF header
      description: 'Parse VCF header and return list of sample names.


        Usage: User uploads joint VCF, frontend calls this endpoint to discover

        sample names, then presents sample -> role mapping UI before final ingestion.


        Epic 1 scope: backend detection only. Auto-inference of roles deferred to

        Epic 4-5 (UI-driven).'
      operationId: validate_multisample_vcf_api_v1_vcf_validate_multisample_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VcfValidateMultisampleRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VcfValidateMultisampleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/families/from-joint-vcf:
    post:
      tags:
      - families
      summary: Create family + sessions from joint VCF (atomic)
      description: 'Atomically create family + N sessions from joint VCF.


        Flow:

        1. Parse VCF header to get actual sample names

        2. Validate user-provided sample_role_mapping against actual samples

        (Case A/B/C/D per CR NB-6)

        3. Call SO atomic endpoint POST /internal/families/with-sessions

        4. Return family + session IDs


        Atomicity guaranteed by SO transaction layer (Jules point 4).


        HEL-CR-FAMILY-EPIC-1-001'
      operationId: create_family_from_joint_vcf_api_v1_families_from_joint_vcf_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFamilyFromJointVcfRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyFromJointVcfResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/families/from-separate-vcfs:
    post:
      tags:
      - families
      summary: Create family + sessions from individual single-sample VCFs (atomic)
      description: 'Atomically create family + N sessions from individual single-sample VCFs.


        Flow:

        1. Validate inheritance_hypothesis, family_role, affected_status per member.

        2. For each member: parse VCF header to confirm single-sample (reject

        multi-sample VCFs with 400 + redirect to /families/from-joint-vcf).

        3. Build session_specs with vcf_sample_name extracted from each VCF

        (single sample per file). vcf_mode set to "separate" via metadata.

        4. Call SO atomic endpoint POST /internal/families/with-sessions.

        5. Return family + session_ids.


        Atomicity guaranteed by SO transaction layer.


        HELIX-CR-2026-FAMILY-FRONTEND-001 Phase 3-B.'
      operationId: create_family_from_separate_vcfs_api_v1_families_from_separate_vcfs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFamilyFromSeparateVcfsRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyFromJointVcfResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    CreateFamilyFromJointVcfRequest:
      properties:
        vcf_file_path:
          type: string
          title: Vcf File Path
        family_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Family Name
        family_notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Family Notes
        inheritance_hypothesis:
          anyOf:
          - type: string
          - type: 'null'
          title: Inheritance Hypothesis
        sample_role_mapping:
          items:
            $ref: '#/components/schemas/JointVcfSampleMapping'
          type: array
          title: Sample Role Mapping
        staging_session_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Staging Session Id
        filtering_preset:
          type: string
          title: Filtering Preset
          description: 'Quality filtering preset. Controls which low-quality variants are removed before annotation. Options: strict (default, quality>=30/depth>=20/GQ>=30), balanced (20/15/20), permissive (10/10/10), custom.'
          default: strict
      type: object
      required:
      - vcf_file_path
      - sample_role_mapping
      title: CreateFamilyFromJointVcfRequest
      description: POST /api/v1/families/from-joint-vcf request body.
    FamilyFromJointVcfResponse:
      properties:
        family:
          $ref: '#/components/schemas/FamilyPublicResponse'
        session_ids:
          items:
            type: string
          type: array
          title: Session Ids
      type: object
      required:
      - family
      - session_ids
      title: FamilyFromJointVcfResponse
      description: Response after atomic family + sessions creation from joint VCF.
    FamilyPublicResponse:
      properties:
        id:
          type: string
          title: Id
        created_by:
          type: string
          title: Created By
        organization_id:
          type: string
          title: Organization Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
        inheritance_hypothesis:
          anyOf:
          - type: string
          - type: 'null'
          title: Inheritance Hypothesis
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
      type: object
      required:
      - id
      - created_by
      - organization_id
      title: FamilyPublicResponse
      description: Family representation in public API.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    JointVcfSampleMapping:
      properties:
        sample_name:
          type: string
          title: Sample Name
        family_role:
          type: string
          title: Family Role
        affected_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Affected Status
        sex:
          anyOf:
          - type: string
          - type: 'null'
          title: Sex
        clinical_profile:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Clinical Profile
      type: object
      required:
      - sample_name
      - family_role
      title: JointVcfSampleMapping
      description: 'Single sample to role mapping for joint VCF family creation.


        HELIX-CR-2026-FAMILY-FRONTEND-001 Phase 3-B: added sex field for

        inheritance pattern analysis (X-linked, hemizygous calling, mtDNA).


        HELIX-CR-2026-FAMILY-CLINICAL-PIPELINE-ARCHITECTURE-001: added

        clinical_profile for proband HPO transport from /create/trio flow.

        Frontend supplies a non-None dict only on the proband mapping;

        parent mappings carry None. SO writes NDJSON to disk before dispatch

        when this field is present in the corresponding session spec.

        Dict matches ClinicalProfileRequest schema shape.'
    VcfValidateMultisampleRequest:
      properties:
        vcf_file_path:
          type: string
          title: Vcf File Path
      type: object
      required:
      - vcf_file_path
      title: VcfValidateMultisampleRequest
      description: POST /api/v1/vcf/validate-multisample request.
    SeparateVcfMemberSpec:
      properties:
        vcf_file_path:
          type: string
          title: Vcf File Path
        family_role:
          type: string
          title: Family Role
        affected_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Affected Status
        case_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Case Label
        sex:
          anyOf:
          - type: string
          - type: 'null'
          title: Sex
        staging_session_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Staging Session Id
        clinical_profile:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Clinical Profile
      type: object
      required:
      - vcf_file_path
      - family_role
      title: SeparateVcfMemberSpec
      description: 'Single member spec for separate-mode trio upload.


        Each member is a single-sample VCF (1 sample per file). Distinct from

        JointVcfSampleMapping which references a sample WITHIN a multi-sample VCF.


        Phase 3-B: sex field added (Jules N1 review 2026-05-08) for inheritance

        analysis. Optional with WARN log on emit if NULL (architectural lock).


        HELIX-CR-2026-FAMILY-CLINICAL-PIPELINE-ARCHITECTURE-001: added

        clinical_profile for proband HPO transport from /create/trio flow.

        Frontend supplies a non-None dict only on the proband member;

        parent members carry None. SO writes NDJSON before dispatch.'
    CreateFamilyFromSeparateVcfsRequest:
      properties:
        family_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Family Name
        family_notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Family Notes
        inheritance_hypothesis:
          anyOf:
          - type: string
          - type: 'null'
          title: Inheritance Hypothesis
        members:
          items:
            $ref: '#/components/schemas/SeparateVcfMemberSpec'
          type: array
          maxItems: 3
          minItems: 3
          title: Members
          description: 'Exactly 3 member specs: proband, father, mother. HELIX-CR-2026-TRIO-GVCF-WIRING-001 / Jules review cycle 2 B4b -- a trio is exactly three members. Quad / extended-pedigree analysis is a separate future CR with its own orchestrator and its own de novo mathematics; it is not an N-range widening of this endpoint.'
        filtering_preset:
          type: string
          title: Filtering Preset
          description: 'Quality filtering preset. Controls which low-quality variants are removed before annotation. Options: strict (default, quality>=30/depth>=20/GQ>=30), balanced (20/15/20), permissive (10/10/10), custom.'
          default: strict
      type: object
      required:
      - members
      title: CreateFamilyFromSeparateVcfsRequest
      description: 'POST /api/v1/families/from-separate-vcfs request body.


        Use case: lab uploads 3 individual single-sample VCFs (proband, father,

        mother), each with one sample. Less common clinically than joint VCF

        (CellGenetics primarily uses joint), but supported.'
    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
    VcfValidateMultisampleResponse:
      properties:
        sample_names:
          items:
            type: string
          type: array
          title: Sample Names
        sample_count:
          type: integer
          title: Sample Count
      type: object
      required:
      - sample_names
      - sample_count
      title: VcfValidateMultisampleResponse
      description: VCF multi-sample validation response.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer