---
title: "Resolve and interpret one public GRCh38 variant query"
method: POST
path: "/public/v1/variants/search"
tags: ["public-variants"]
---

# Resolve and interpret one public GRCh38 variant query

`POST /public/v1/variants/search`

## 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/public/v1/variants/search`
- Auth: none declared

Resolve one bounded query and interpret only one unique identity.

## Request body

- object
  - `assembly` 'GRCh38', required
  - `query` string, required

## Response `200`

Successful Response

- union
  - PublicVariantSearchResolvedResponse
    - `search_contract_version` '1.0'
    - `status` 'resolved'
    - `resolution` PublicVariantResolutionMetadata, required
      - `normalized_query` string, required
      - `notation_family` 'coordinate' | 'genomic_hgvs' | 'transcript_hgvs' | 'protein_hgvs' | 'spdi' | 'rsid' | 'identifier' | 'gene', required
      - `input_accession` string, nullable, required
      - `input_version` string, nullable, required
      - `resolver_schema_version` string, required
      - `resolver_asset_version` string, required
      - `mapping_sources` PublicVariantMappingSource[], required
        - `name` string, required
        - `version` string, required
      - `warnings` string[], required
    - `identity` PublicVariantIdentity, required
      - `assembly` 'GRCh38', required
      - `chromosome` string, required
      - `position` integer, required
      - `reference` string, required
      - `alternate` string, required
      - `variant_type` 'SNV' | 'INS' | 'DEL' | 'DELINS', required
      - `canonical_key` string, required
    - `interpretation` union, required
      - PublicVariantSuccessResponse
        - `transcript_representations` object, nullable
        - `contract_version` '1.0'
        - `status` 'success'
        - `identity` PublicVariantIdentity, required
          - `assembly` 'GRCh38', required
          - `chromosome` string, required
          - `position` integer, required
          - `reference` string, required
          - `alternate` string, required
          - `variant_type` 'SNV' | 'INS' | 'DEL' | 'DELINS', required
          - `canonical_key` string, required
        - `display` PublicVariantDisplay, required
          - `label` string, required
          - `hgvs_genomic` string, nullable, required
          - `hgvs_cdna` string, nullable, required
          - `hgvs_protein` string, nullable, required
        - `annotation` PublicVariantAnnotation, required
          - `gene_symbol` string, required
          - `gene_id` string, nullable, required
          - `transcript_id` string, nullable, required
          - `consequence` string, required
          - `impact` string, nullable, required
          - `biotype` string, nullable, required
          - `exon_number` string, nullable, required
          - `domains` string[], required
        - `evidence` PublicVariantEvidence, required
          - `clinvar_significance` string, nullable, required
          - `clinvar_review_stars` integer, nullable, required
          - `vcep_applied` boolean, required
          - `vcep_panel` string, nullable, required
          - `erepo_assertion` string, nullable, required
          - `erepo_panel` string, nullable, required
          - `erepo_disease` string, nullable, required
          - `clinvar` PublicClinVarEvidence, required
            - `clinical_significance` string, nullable, required
            - `review_status` string, nullable, required
            - `review_stars` integer, nullable, required
            - `variation_id` string, nullable, required
            - `rsid` string, nullable, required
            - `disease_names` string[], required
            - `protein_representation` string, nullable, required
            - `canonical_url` string, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `expert` PublicExpertEvidence, required
            - `vcep_applied` boolean, required
            - `vcep_panel` string, nullable, required
            - `erepo_assertion` string, nullable, required
            - `erepo_panel` string, nullable, required
            - `erepo_disease` string, nullable, required
            - `erepo_summary` string, nullable, required
            - `erepo_url` string, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `predictors` PublicPredictorEvidence, required
            - `sift` PublicPrediction, required
              - …
            - `alphamissense` PublicPrediction, required
              - …
            - `metasvm` PublicPrediction, required
              - …
            - `dann_score` number, nullable, required
            - `bayesdel_noaf` PublicPrediction, required
              - …
            - `bayesdel_addaf` PublicPrediction, required
              - …
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `spliceai` PublicSpliceAIEvidence, required
            - `prediction` string, nullable, required
            - `max_delta_score` number, nullable, required
            - `gene` string, nullable, required
            - `ds_ag` number, nullable, required
            - `ds_al` number, nullable, required
            - `ds_dg` number, nullable, required
            - `ds_dl` number, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `conservation` PublicConservationEvidence, required
            - `phylop100way_vertebrate` number, nullable, required
            - `gerp_rs` number, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `gene_constraints` PublicGeneConstraintEvidence, required
            - `pli` number, nullable, required
            - `oe_lof` number, nullable, required
            - `loeuf` number, nullable, required
            - `missense_z` number, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `dosage` PublicDosageEvidence, required
            - `haploinsufficiency_score` integer, nullable, required
            - `triplosensitivity_score` integer, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `population` PublicPopulationEvidence, required
            - `global_allele_frequency` number, nullable, required
            - `global_allele_count` integer, nullable, required
            - `global_allele_number` integer, nullable, required
            - `homozygote_count` integer, nullable, required
            - `group_max_allele_frequency` number, nullable, required
            - `popmax_population` string, nullable, required
            - `rsid` string, nullable, required
            - `canonical_url` string, nullable, required
            - `availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
          - `external_links` PublicExternalLinks, required
            - `clinvar` string, nullable, required
            - `gnomad` string, nullable, required
            - `ensembl_gene` string, nullable, required
            - `ensembl_transcript` string, nullable, required
            - `clingen_erepo` string, nullable, required
        - `classification` PublicVariantClassification, required
          - `functional_evidence` PublicFunctionalEvidence
            - `qualification_profile` 'scott-mmr-dms-2022.v1', required
            - `combining_policy` 'existing_classifier', required
            - `combining_policy_version` string, required
            - `gn137_combining_rules_applied` false, required
            - `records` PublicFunctionalRecord[], required
              - …
          - `framework` 'acmg_2015', required
          - `automated_class` 'P' | 'LP' | 'VUS' | 'LB' | 'B', required
          - `criteria` string, required
          - `confidence_score` number, required
          - `pm1_evidence_source` 'pfam' | 'uniprot' | 'pfam+uniprot', nullable, required
          - `pm1_evidence_availability` 'available' | 'no_record' | 'not_applicable' | 'unavailable', required
        - `provenance` PublicVariantProvenance, required
          - `annotation_source` 'vep_cache' | 'vep_live', nullable, required
          - `vep_version` string, required
          - `vep_cache_version` string, required
          - `reference_assembly` string, required
          - `classifier_version` string, required
          - `classifier_version_label` string, required
          - `reference_versions` PublicReferenceVersion[], required
            - `name` string, required
            - `version` string, required
          - `annotation_resolved` boolean, required
          - `classification_completed` boolean, required
        - `warnings` string[], required
        - `limitations` PublicVariantLimitations, required
          - `scope` 'Automated variant-level ACMG/AMP decision support for one GRCh38 nuclear SNV, simple indel, or delins smaller than 50 bp.'
          - `unavailable_context` 'Patient phenotype, genotype, family, segregation, de novo, case-specific, and private override evidence were not evaluated.'
          - `diagnostic_use` 'This result is not a patient diagnosis and must not be used as a substitute for qualified clinical interpretation.'
      - PublicVariantUnavailableResponse
        - `contract_version` '1.0'
        - `status` 'unavailable'
        - `identity` PublicVariantIdentity, required
          - `assembly` 'GRCh38', required
          - `chromosome` string, required
          - `position` integer, required
          - `reference` string, required
          - `alternate` string, required
          - `variant_type` 'SNV' | 'INS' | 'DEL' | 'DELINS', required
          - `canonical_key` string, required
        - `display` PublicVariantDisplay, required
          - `label` string, required
          - `hgvs_genomic` string, nullable, required
          - `hgvs_cdna` string, nullable, required
          - `hgvs_protein` string, nullable, required
        - `error` PublicVariantUnavailableError, required
          - `code` 'annotation_unavailable' | 'reference_data_unavailable' | 'classification_unavailable', required
          - `message` string, required
          - `retryable` true
        - `provenance` PublicVariantProvenance, required
          - `annotation_source` 'vep_cache' | 'vep_live', nullable, required
          - `vep_version` string, required
          - `vep_cache_version` string, required
          - `reference_assembly` string, required
          - `classifier_version` string, required
          - `classifier_version_label` string, required
          - `reference_versions` PublicReferenceVersion[], required
            - `name` string, required
            - `version` string, required
          - `annotation_resolved` boolean, required
          - `classification_completed` boolean, required
        - `warnings` string[], required
        - `limitations` PublicVariantLimitations, required
          - `scope` 'Automated variant-level ACMG/AMP decision support for one GRCh38 nuclear SNV, simple indel, or delins smaller than 50 bp.'
          - `unavailable_context` 'Patient phenotype, genotype, family, segregation, de novo, case-specific, and private override evidence were not evaluated.'
          - `diagnostic_use` 'This result is not a patient diagnosis and must not be used as a substitute for qualified clinical interpretation.'
  - PublicVariantSearchAmbiguousResponse
    - `search_contract_version` '1.0'
    - `status` 'ambiguous'
    - `resolution` PublicVariantResolutionMetadata, required
      - `normalized_query` string, required
      - `notation_family` 'coordinate' | 'genomic_hgvs' | 'transcript_hgvs' | 'protein_hgvs' | 'spdi' | 'rsid' | 'identifier' | 'gene', required
      - `input_accession` string, nullable, required
      - `input_version` string, nullable, required
      - `resolver_schema_version` string, required
      - `resolver_asset_version` string, required
      - `mapping_sources` PublicVariantMappingSource[], required
        - `name` string, required
        - `version` string, required
      - `warnings` string[], required
    - `error` PublicVariantSearchError, required
      - `code` 'ambiguous_variant' | 'variant_not_found', required
      - `message` string, required
      - `retryable` false
    - `total_candidate_count` integer, required
    - `candidates_truncated` boolean, required
    - `candidates` PublicVariantSearchCandidate[], required
      - `identity` PublicVariantIdentity, required
        - `assembly` 'GRCh38', required
        - `chromosome` string, required
        - `position` integer, required
        - `reference` string, required
        - `alternate` string, required
        - `variant_type` 'SNV' | 'INS' | 'DEL' | 'DELINS', required
        - `canonical_key` string, required
      - `gene_symbol` string, nullable, required
      - `transcript_id` string, nullable, required
      - `hgvs_genomic` string, nullable, required
      - `hgvs_cdna` string, nullable, required
      - `hgvs_protein` string, nullable, required
  - PublicVariantSearchNotFoundResponse
    - `search_contract_version` '1.0'
    - `status` 'not_found'
    - `resolution` PublicVariantResolutionMetadata, required
      - `normalized_query` string, required
      - `notation_family` 'coordinate' | 'genomic_hgvs' | 'transcript_hgvs' | 'protein_hgvs' | 'spdi' | 'rsid' | 'identifier' | 'gene', required
      - `input_accession` string, nullable, required
      - `input_version` string, nullable, required
      - `resolver_schema_version` string, required
      - `resolver_asset_version` string, required
      - `mapping_sources` PublicVariantMappingSource[], required
        - `name` string, required
        - `version` string, required
      - `warnings` string[], required
    - `error` PublicVariantSearchError, required
      - `code` 'ambiguous_variant' | 'variant_not_found', required
      - `message` string, required
      - `retryable` false
  - PublicVariantSearchInvalidRequestResponse
    - `search_contract_version` '1.0'
    - `status` 'invalid_request'
    - `resolution` PublicVariantResolutionMetadata
      - `normalized_query` string, required
      - `notation_family` 'coordinate' | 'genomic_hgvs' | 'transcript_hgvs' | 'protein_hgvs' | 'spdi' | 'rsid' | 'identifier' | 'gene', required
      - `input_accession` string, nullable, required
      - `input_version` string, nullable, required
      - `resolver_schema_version` string, required
      - `resolver_asset_version` string, required
      - `mapping_sources` PublicVariantMappingSource[], required
        - `name` string, required
        - `version` string, required
      - `warnings` string[], required
    - `error` PublicVariantSearchInvalidRequestError, required
      - `code` 'invalid_envelope' | 'query_too_long' | 'invalid_characters' | 'malformed_coordinate' | 'malformed_hgvs' | 'malformed_spdi' | 'malformed_rsid' | 'reference_mismatch' | 'invalid_allele_class', required
      - `message` string, required
      - `retryable` false
  - PublicVariantSearchUnsupportedResponse
    - `search_contract_version` '1.0'
    - `status` 'unsupported'
    - `resolution` PublicVariantResolutionMetadata
      - `normalized_query` string, required
      - `notation_family` 'coordinate' | 'genomic_hgvs' | 'transcript_hgvs' | 'protein_hgvs' | 'spdi' | 'rsid' | 'identifier' | 'gene', required
      - `input_accession` string, nullable, required
      - `input_version` string, nullable, required
      - `resolver_schema_version` string, required
      - `resolver_asset_version` string, required
      - `mapping_sources` PublicVariantMappingSource[], required
        - `name` string, required
        - `version` string, required
      - `warnings` string[], required
    - `error` PublicVariantSearchUnsupportedError, required
      - `code` 'unsupported_assembly' | 'unsupported_query_type' | 'unsupported_accession' | 'unsupported_hgvs_expression' | 'unsupported_variant_class' | 'mitochondrial_not_supported' | 'structural_variant_not_supported', required
      - `message` string, required
      - `retryable` false
  - PublicVariantSearchUnavailableResponse
    - `search_contract_version` '1.0'
    - `status` 'resolution_unavailable'
    - `resolution` PublicVariantResolutionMetadata
      - `normalized_query` string, required
      - `notation_family` 'coordinate' | 'genomic_hgvs' | 'transcript_hgvs' | 'protein_hgvs' | 'spdi' | 'rsid' | 'identifier' | 'gene', required
      - `input_accession` string, nullable, required
      - `input_version` string, nullable, required
      - `resolver_schema_version` string, required
      - `resolver_asset_version` string, required
      - `mapping_sources` PublicVariantMappingSource[], required
        - `name` string, required
        - `version` string, required
      - `warnings` string[], required
    - `error` PublicVariantSearchUnavailableError, required
      - `code` 'resolver_asset_unavailable' | 'resolver_asset_incompatible' | 'reference_fasta_unavailable' | 'resolver_timeout', required
      - `message` string, required
      - `retryable` true

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `413`: Request Entity Too Large
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable
- `504`: Gateway Timeout

---

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