---
title: "Create family + sessions from individual single-sample VCFs (atomic)"
method: POST
path: "/api/v1/families/from-separate-vcfs"
tags: ["families"]
---

# Create family + sessions from individual single-sample VCFs (atomic)

`POST /api/v1/families/from-separate-vcfs`

## 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/api/v1/families/from-separate-vcfs`
- Auth: HTTP bearer

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.

## Request body

- CreateFamilyFromSeparateVcfsRequest: 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.
  - `family_name` string, nullable
  - `family_notes` string, nullable
  - `inheritance_hypothesis` string, nullable
  - `members` SeparateVcfMemberSpec[], required: 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.
    - `vcf_file_path` string, required
    - `family_role` string, required
    - `affected_status` string, nullable
    - `case_label` string, nullable
    - `sex` string, nullable
    - `staging_session_id` string, uuid, nullable
    - `clinical_profile` object, nullable
  - `filtering_preset` string: 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.

## Response `201`

Successful Response

- FamilyFromJointVcfResponse: Response after atomic family + sessions creation from joint VCF.
  - `family` FamilyPublicResponse, required: Family representation in public API.
    - `id` string, required
    - `created_by` string, required
    - `organization_id` string, required
    - `name` string, nullable
    - `notes` string, nullable
    - `inheritance_hypothesis` string, nullable
    - `created_at` string, nullable
    - `updated_at` string, nullable
  - `session_ids` string[], required

## 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)