VarSy API Documentation

Documentation to access VarSy through Web-APIs. To simplify generating and assessing synonyms for variants, we strive to minimize the number of endpoints.

API key

Please log in to view your API key.

Authentication

1. Request Header:

Include the apikey in request header. For example:

Example Request

curl -H 'apikey: 'YOUR API KEY'' https://varsy.co/api/v1/:path_params

2. Request Parameter:

Include the apikey as parameter. For example:

Example Request

curl https://varsy.co/api/v1/:path_params?apikey='YOUR API KEY'"

Exact

GET /api/v1/alleles

Fetch mappings for unambiguous HGVS‐style variants. Only c. and g. notations that map one-to-one to a reference sequences are supported here. Protein (p.)-level descriptions may correspond to multiple c. and g. variants, so they aren’t supported on this endpoint—please use the fuzzy endpoint for those cases.

Required Parameters

hgvs (string) – Unambiguous HGVS notation (c. or g.), e.g. NM_145068.4:c.1718_1719delinsTT.

Usage Notes

The hgvs query parameter must exactly follow standard HGVS nomenclature for variant.
Ensure your client URL-encodes special characters (e.g. +).
Ensure your HGVS expression has no spaces.
Donot provide p. HGVS expression at this end-point

Response (example)

Request: GET https://varsy.co/api/v1/alleles?hgvs=NM_145068.4:c.1718G%3ET&apikey='YOUR API KEY'

Response code: 200

{
  "cdots": [
    {
      "gene": "TRPV3",
      "protein_hgvs": "NP_001245134.1:p.(Gly573Val)",
      "transcript_hgvs": "NM_001258205.2:c.1718G>T",
      "variant_position_marker": "12:140:25:5"
    },
    {
      "gene": "TRPV3",
      "protein_hgvs": "NP_659505.1:p.(Gly573Val)",
      "transcript_hgvs": "NM_145068.4:c.1718G>T",
      "variant_position_marker": "12:140:25:5"
    }
  ],
  "gdots": [
    {
      "genomic_hgvs": "NC_000017.11:g.3524223C>A"
    },
    {
      "genomic_hgvs": "NC_060941.1:g.3413102C>A"
    },
    {
      "genomic_hgvs": "NC_000017.10:g.3427517C>A"
    }
  ]
}

Response (example)

Request: GET https://varsy.co/api/v1/alleles?hgvs=NM_14503368.4:c.1718G%3ET&apikey='YOUR API KEY'

Response code: 200

{
  "error_code": 401,
  "error_message": "The sequence (transcript or non-reference genome sequence) is not present in the alignments that are present in dataset. Alleley retrieves alignments of non-reference sequences to reference genome from NCBI database. Likely the sequence is absent in the source alignment. This might happen if the sequence is replaced with a newer sequence in NCBI reference sequence."
}

Approximate

GET /api/v1/fuzzy

Perform protein‐level variant lookups that may map to multiple c. and g. changes even on one sequence.

Required Parameters

Exactly one of:
- gene (string) – HGNC gene symbol, e.g. DKC1
- protein_id (string) – RefSeq protein ID, e.g. NP_001354.1
Plus:
- var (string) – Protein‐level change, e.g. p.Leu72Tyr.

Response (example)

Request: GET https://varsy.co/api/v1/fuzzy?gene=DKC1&var=p.Leu72Tyr&apikey='YOUR API KEY'

Response code: 200

{
  "mappings": [
    {
      "mapping": {
        "cdots": [
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001135935.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001142463.3:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:11"
          },
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001275676.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001288747.2:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:10"
          },
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001354.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001363.5:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:11"
          }
        ],
        "gdots": [
          {
            "genomic_hgvs": "NC_000023.11:g.154765949_154765950delinsTA"
          },
          {
            "genomic_hgvs": "NC_060947.1:g.153002359_153002360delinsTA"
          },
          {
            "genomic_hgvs": "NC_000023.10:g.153994224_153994225delinsTA"
          }
        ]
      },
      "transcript": "NM_001363.5"
    },
    {
      "mapping": {
        "cdots": [
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001135935.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001142463.3:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:11"
          },
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001275676.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001288747.2:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:10"
          },
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001354.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001363.5:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:11"
          }
        ],
        "gdots": [
          {
            "genomic_hgvs": "NC_000023.11:g.154765949_154765950delinsTA"
          },
          {
            "genomic_hgvs": "NC_060947.1:g.153002359_153002360delinsTA"
          },
          {
            "genomic_hgvs": "NC_000023.10:g.153994224_153994225delinsTA"
          }
        ]
      },
      "transcript": "NM_001142463.3"
    },
    {
      "mapping": {
        "cdots": [
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001135935.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001142463.3:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:11"
          },
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001275676.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001288747.2:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:10"
          },
          {
            "gene": "DKC1",
            "protein_hgvs": "NP_001354.1:p.(Leu72Tyr)",
            "transcript_hgvs": "NM_001363.5:c.214_215delinsTA",
            "variant_position_marker": "3:42:48:11"
          }
        ],
        "gdots": [
          {
            "genomic_hgvs": "NC_000023.11:g.154765949_154765950delinsTA"
          },
          {
            "genomic_hgvs": "NC_060947.1:g.153002359_153002360delinsTA"
          },
          {
            "genomic_hgvs": "NC_000023.10:g.153994224_153994225delinsTA"
          }
        ]
      },
      "transcript": "NM_001288747.2"
    }
  ]
}

Response (example)

Request: GET https://varsy.co/api/v1/alleles?gene=ADENINE12&var=p.Leu72Tyr&apikey='YOUR API KEY'

Response code: 200

{
  "error_code": 401,
  "error_message": "The Gene ADENINE12 which you queried is not found. Please make sure the gene is a valid one."
}

Response (example)

Request: GET https://varsy.co/api/v1/alleles?gene=DKC1&var=p.Leu736Tyr&apikey='YOUR API KEY'

Response code: 200

{
  "mappings": [
    {
      "mapping": {
        "error_code": 401,
        "error_message": "The protein sequence with id: NP_001354.1 is '514' long, the position requested for fuzzy mapping: '736' falls outside this region."
      },
      "transcript": "NM_001363.5"
    },
    {
      "mapping": {
        "error_code": 401,
        "error_message": "The protein sequence with id: NP_001135935.1 is '509' long, the position requested for fuzzy mapping: '736' falls outside this region."
      },
      "transcript": "NM_001142463.3"
    },
    {
      "mapping": {
        "error_code": 401,
        "error_message": "The protein sequence with id: NP_001275676.1 is '420' long, the position requested for fuzzy mapping: '736' falls outside this region."
      },
      "transcript": "NM_001288747.2"
    }
  ]
}