Skip to content

Managing Samples

Create and manage samples (specimens) using the iFlow CLI.

Overview

Samples represent biological specimens in the iFlow platform. Each sample:

  • Belongs to a subject - Linked via --subject-id
  • Has clinical metadata - Sample type, tissue, barcode, etc.
  • Has custom properties - Specimen details, sequencing info, etc.
  • Can generate sampleinfo - Pipeline-ready JSON for workflow submission

Prerequisites

  1. Installed CLI - See Installation
  2. Authenticated - Run iflow login
  3. Project selected - Run iflow config select-project
  4. Subject created - See Managing Subjects

Listing Samples

iflow samples list
iflow samples list --sample-type germline
iflow samples list --limit 50

Creating Samples

Only --display-id and --subject-id are dedicated flags. Everything else uses --property/-P:

# Basic sample
iflow samples create --subject-id SUBJECT_ID -n "NA12878"

# With clinical metadata
iflow samples create \
  --subject-id SUBJECT_ID \
  -n "SAM-2026-001" \
  -P sample_type=somatic \
  -P tissue=lung \
  -P specimen_type=FFPE \
  -P specimen_id=SPEC-001 \
  -P collection_date=2026-01-15 \
  -P sequencing_date=2026-01-20

# With tags
iflow samples create \
  --subject-id SUBJECT_ID \
  -n "SAM-2026-002" \
  -P sample_type=germline \
  -t hereditary -t wes

Property Types

Model columns (stored as dedicated database fields):

Key Description
sample_type germline, somatic, ffpe, liquid_biopsy, unknown
external_id External system reference
barcode Sample barcode
tissue Tissue type
collection_date Date of collection (YYYY-MM-DD)
notes Free-text notes

Custom properties (stored in JSONB):

Key Description
specimen_type FFPE, Blood, Saliva, etc.
specimen_id Specimen identifier
sequencing_date Date of sequencing
sequencing_type WGS, WES, Panel, etc.
source Sample source description

Create Options

Option Description
--subject-id Parent subject ID (required)
-n, --display-id Sample display ID (required)
-P, --property Property key=value (repeatable)
-t, --tag Tag (repeatable)
-p, --project Project ID (uses default)
--curl Output curl command

Getting Sample Details

iflow samples get SAMPLE_ID

Output:

Sample: SAM-2026-001
  ID: abc123-def456-...
  Subject ID: xyz789-...
  Type: somatic
  Status: pending
  Tissue: lung
  Created: 2026-01-15T10:00:00Z
  Tags: hereditary, wes
  Properties:
    specimen_type: FFPE
    specimen_id: SPEC-001
    sequencing_date: 2026-01-20

Generating Sampleinfo

Generate pipeline-ready JSON from subject + sample metadata:

iflow samples sampleinfo SAMPLE_ID

Output:

{
  "name": "Jane",
  "surname": "Doe",
  "sex": "female",
  "birth_date": "1985-03-15",
  "accession_id": "ACC-12345",
  "specimen_type": "FFPE",
  "source": "lung",
  "sequencing_type": "WES"
}

With Order Context

Include order metadata (ordering physician, institution):

iflow samples sampleinfo SAMPLE_ID --order-id ORDER_ID

Pipe into Pipeline Run

iflow analyses submit \
  --pipeline hereditary-mock \
  --input-json "$(iflow samples sampleinfo SAMPLE_ID)" \
  --watch

Deleting Samples

iflow samples delete SAMPLE_ID

You'll be prompted to confirm.

API Access

curl -X POST https://miner.flow.labpgx.com/api/v1/samples \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "SUBJECT_ID",
    "display_id": "SAM-2026-001",
    "sample_type": "somatic",
    "properties": {
      "specimen_type": "FFPE",
      "specimen_id": "SPEC-001",
      "collection_date": "2026-01-15"
    }
  }'

curl https://miner.flow.labpgx.com/api/v1/samples/SAMPLE_ID/sampleinfo \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID"

curl "https://miner.flow.labpgx.com/api/v1/samples/SAMPLE_ID/sampleinfo?order_id=ORDER_ID" \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: PROJECT_ID"

Next Steps