{ "openapi": "3.0.3", "info": { "title": "SynVar public API", "version": "1.0.0", "description": "Recognise variants, map between protein, coding DNA and genomic coordinates, and generate synonyms or normalised representations. No authentication is required.\n\nChoose `format=vrs` for structured normalisation, or `format=xml/json` with `mode=expand` for synonyms.\n\nProtein inputs and registry IDs may resolve to several alleles. Results depend on available references and mapping services; an empty result does not establish that the input is biologically invalid." }, "servers": [ { "url": ".", "description": "Current SynVar server" } ], "tags": [ { "name": "Variants", "description": "Variant expansion and normalisation" } ], "paths": { "/api": { "get": { "tags": [ "Variants" ], "summary": "Expand or normalise a variant", "operationId": "getVariants", "description": "Example variants include their reference, so ref can be left empty. After Execute, the request URL, curl command and server response appear below. Boolean parameters accept true/false (also on/off).", "parameters": [ { "$ref": "#/components/parameters/variant" }, { "$ref": "#/components/parameters/ref" }, { "$ref": "#/components/parameters/mode" }, { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/level" }, { "$ref": "#/components/parameters/assembly" }, { "$ref": "#/components/parameters/searchGenes" }, { "$ref": "#/components/parameters/map" }, { "$ref": "#/components/parameters/iso" }, { "$ref": "#/components/parameters/startMet" }, { "$ref": "#/components/parameters/insForDup" }, { "$ref": "#/components/parameters/leftAlign" }, { "$ref": "#/components/parameters/cache" }, { "$ref": "#/components/parameters/norm" } ], "responses": { "200": { "$ref": "#/components/responses/VariantResult" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Variants" ], "summary": "Expand or normalise using form data", "operationId": "postVariants", "description": "Same processing and parameters as GET. Submit application/x-www-form-urlencoded fields; raw JSON request bodies are not supported. Boolean parameters accept true/false (also on/off).", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/VariantRequest" }, "examples": { "protein": { "summary": "BRAF V600E: literature shorthand", "value": { "variant": "BRAF V600E", "level": "any", "mode": "normalize", "format": "vrs" } }, "hgvs": { "summary": "BRAF: explicit transcript HGVS", "value": { "variant": "NM_004333.6:c.1799T>A", "level": "any", "mode": "normalize", "format": "vrs" } }, "spdi": { "summary": "BRAF: genomic SPDI", "value": { "variant": "NC_000007.14:140753335:A:T", "level": "any", "mode": "normalize", "format": "vrs" } }, "dbsnp": { "summary": "BRAF: dbSNP (may resolve to several alleles)", "value": { "variant": "rs113488022", "level": "any", "mode": "normalize", "format": "vrs" } }, "clingen": { "summary": "BRAF: ClinGen Allele Registry", "value": { "variant": "CA123643", "level": "any", "mode": "normalize", "format": "vrs" } }, "deletion": { "summary": "PTEN: transcript deletion", "value": { "variant": "NM_000314.8:c.833del", "level": "any", "mode": "normalize", "format": "vrs" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/VariantResult" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "parameters": { "variant": { "name": "variant", "in": "query", "required": true, "description": "Required variant description or free text. Accepts HGVS, literature shorthand, rsIDs, ClinGen CA IDs, SPDI, VCF-like input, IVS, LRG and supported Ensembl accessions. Include the gene/reference in this field or provide ref.", "schema": { "$ref": "#/components/schemas/variantInput" }, "examples": { "protein": { "summary": "BRAF V600E: literature shorthand", "value": "BRAF V600E" }, "hgvs": { "summary": "BRAF: explicit transcript HGVS", "value": "NM_004333.6:c.1799T>A" }, "spdi": { "summary": "BRAF: genomic SPDI", "value": "NC_000007.14:140753335:A:T" }, "dbsnp": { "summary": "BRAF: dbSNP (may resolve to several alleles)", "value": "rs113488022" }, "clingen": { "summary": "BRAF: ClinGen Allele Registry", "value": "CA123643" }, "deletion": { "summary": "PTEN: transcript deletion", "value": "NM_000314.8:c.833del" } } }, "ref": { "name": "ref", "in": "query", "required": false, "description": "Optional gene, chromosome or sequence accession (RefSeq, supported Ensembl or LRG). Not required when the input already contains its reference or is a registry identifier.", "schema": { "$ref": "#/components/schemas/refInput" } }, "level": { "name": "level", "in": "query", "required": false, "description": "Input interpretation. any tries protein, transcript, genome, dbSNP and ClinGen until a GRCh38 mapping is found; all combines levels. cdna aliases transcript. genome38/genome37 and genome_grch38/genome_grch37 also select an assembly.", "schema": { "$ref": "#/components/schemas/levelInput" } }, "mode": { "name": "mode", "in": "query", "required": false, "description": "expand generates synonyms and syntactic variations; normalize returns mapped identifiers without broad synonym expansion. norm=true or format=vrs also enables normalisation.", "schema": { "$ref": "#/components/schemas/modeInput" } }, "format": { "name": "format", "in": "query", "required": false, "description": "Response format, independent of the Accept header. xml and json serialize the same result structure. vrs returns a SynVar JSON wrapper containing HGVS, identifiers, SPDI, VCF and VRS objects when available, and always enables normalisation.", "schema": { "$ref": "#/components/schemas/formatInput" } }, "assembly": { "name": "assembly", "in": "query", "required": false, "description": "Restrict genomic output to an assembly; omit or leave empty to allow both. hg19 aliases GRCh37 and hg38 aliases GRCh38. Takes precedence over an assembly specified through level.", "schema": { "$ref": "#/components/schemas/assemblyInput" } }, "searchGenes": { "name": "searchGenes", "in": "query", "required": false, "description": "Discover additional gene names in the variant text. Set false when ref contains trusted context. Explicit accessions embedded in complete HGVS remain usable.", "schema": { "$ref": "#/components/schemas/searchGenesInput" } }, "map": { "name": "map", "in": "query", "required": false, "description": "Require successful genome mapping. If false, expansion may return syntactic variations even when mapping is unavailable.", "schema": { "$ref": "#/components/schemas/mapInput" } }, "iso": { "name": "iso", "in": "query", "required": false, "description": "Expand across all available mapped isoforms. Without this option, MANE Select and UniProt canonical isoforms are included when available.", "schema": { "$ref": "#/components/schemas/isoInput" } }, "startMet": { "name": "startMet", "in": "query", "required": false, "description": "Add protein synonyms at position minus one (numbering without initiator methionine), with a plus-one fallback when validating input.", "schema": { "$ref": "#/components/schemas/startMetInput" } }, "insForDup": { "name": "insForDup", "in": "query", "required": false, "description": "Add insertion-equivalent synonyms for duplications in expansion mode.", "schema": { "$ref": "#/components/schemas/insForDupInput" } }, "leftAlign": { "name": "leftAlign", "in": "query", "required": false, "description": "Add left-aligned and intermediate synonyms for deletions and duplications in repetitive regions in expansion mode.", "schema": { "$ref": "#/components/schemas/leftAlignInput" } }, "cache": { "name": "cache", "in": "query", "required": false, "description": "true reads and writes the mapping cache; false bypasses reads and writes; refresh bypasses reads and updates the cache. Disabled aliases: off, no, 0. Refresh alias: reload.", "schema": { "$ref": "#/components/schemas/cacheInput" } }, "norm": { "name": "norm", "in": "query", "required": false, "description": "Legacy normalisation flag. Prefer mode=normalize. true enables normalisation even when mode=expand.", "schema": { "$ref": "#/components/schemas/normInput" }, "deprecated": true } }, "schemas": { "variantInput": { "type": "string", "description": "Required variant description or free text. Accepts HGVS, literature shorthand, rsIDs, ClinGen CA IDs, SPDI, VCF-like input, IVS, LRG and supported Ensembl accessions. Include the gene/reference in this field or provide ref.", "minLength": 1, "example": "BRAF V600E" }, "refInput": { "type": "string", "description": "Optional gene, chromosome or sequence accession (RefSeq, supported Ensembl or LRG). Not required when the input already contains its reference or is a registry identifier.", "default": "" }, "levelInput": { "type": "string", "description": "Input interpretation. any tries protein, transcript, genome, dbSNP and ClinGen until a GRCh38 mapping is found; all combines levels. cdna aliases transcript. genome38/genome37 and genome_grch38/genome_grch37 also select an assembly.", "enum": [ "any", "protein", "transcript", "cdna", "genome", "genome38", "genome37", "genome_grch38", "genome_grch37", "dbsnp", "clingen", "all" ], "default": "any" }, "modeInput": { "type": "string", "description": "expand generates synonyms and syntactic variations; normalize returns mapped identifiers without broad synonym expansion. norm=true or format=vrs also enables normalisation.", "enum": [ "expand", "normalize" ], "default": "expand" }, "formatInput": { "type": "string", "description": "Response format, independent of the Accept header. xml and json serialize the same result structure. vrs returns a SynVar JSON wrapper containing HGVS, identifiers, SPDI, VCF and VRS objects when available, and always enables normalisation.", "enum": [ "xml", "json", "vrs" ], "default": "xml" }, "assemblyInput": { "type": "string", "description": "Restrict genomic output to an assembly; omit or leave empty to allow both. hg19 aliases GRCh37 and hg38 aliases GRCh38. Takes precedence over an assembly specified through level.", "enum": [ "", "GRCh37", "GRCh38", "hg19", "hg38" ], "default": "" }, "searchGenesInput": { "type": "boolean", "default": true, "description": "Discover additional gene names in the variant text. Set false when ref contains trusted context. Explicit accessions embedded in complete HGVS remain usable." }, "mapInput": { "type": "boolean", "default": false, "description": "Require successful genome mapping. If false, expansion may return syntactic variations even when mapping is unavailable." }, "isoInput": { "type": "boolean", "default": false, "description": "Expand across all available mapped isoforms. Without this option, MANE Select and UniProt canonical isoforms are included when available." }, "startMetInput": { "type": "boolean", "default": false, "description": "Add protein synonyms at position minus one (numbering without initiator methionine), with a plus-one fallback when validating input." }, "insForDupInput": { "type": "boolean", "default": false, "description": "Add insertion-equivalent synonyms for duplications in expansion mode." }, "leftAlignInput": { "type": "boolean", "default": false, "description": "Add left-aligned and intermediate synonyms for deletions and duplications in repetitive regions in expansion mode." }, "cacheInput": { "type": "string", "description": "true reads and writes the mapping cache; false bypasses reads and writes; refresh bypasses reads and updates the cache. Disabled aliases: off, no, 0. Refresh alias: reload.", "enum": [ "true", "false", "refresh" ], "default": "true" }, "normInput": { "type": "boolean", "default": false, "deprecated": true, "description": "Legacy normalisation flag. Prefer mode=normalize. true enables normalisation even when mode=expand." }, "VariantRequest": { "type": "object", "required": [ "variant" ], "properties": { "variant": { "$ref": "#/components/schemas/variantInput" }, "ref": { "$ref": "#/components/schemas/refInput" }, "mode": { "$ref": "#/components/schemas/modeInput" }, "format": { "$ref": "#/components/schemas/formatInput" }, "level": { "$ref": "#/components/schemas/levelInput" }, "assembly": { "$ref": "#/components/schemas/assemblyInput" }, "searchGenes": { "$ref": "#/components/schemas/searchGenesInput" }, "map": { "$ref": "#/components/schemas/mapInput" }, "iso": { "$ref": "#/components/schemas/isoInput" }, "startMet": { "$ref": "#/components/schemas/startMetInput" }, "insForDup": { "$ref": "#/components/schemas/insForDupInput" }, "leftAlign": { "$ref": "#/components/schemas/leftAlignInput" }, "cache": { "$ref": "#/components/schemas/cacheInput" }, "norm": { "$ref": "#/components/schemas/normInput" } } }, "LegacyJsonResult": { "type": "object", "additionalProperties": true, "description": "JSON conversion of the XML tree (no outer description-variant key). XML attributes use @-prefixed keys; attributed text uses value. Repeated variant, isoform, synonym, hgvs, syntactic-variation, vcf and vrs elements are arrays. Structure varies by mode and mapping outcome; an empty result is {}." }, "HgvsRepresentation": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "Reference selection label, such as mane-select, uniprot-canonical or mapped-reference." }, "value": { "type": "string", "description": "HGVS expression." } } }, "VcfRecord": { "type": "object", "required": [ "assembly", "chrom", "pos", "ref", "alt" ], "properties": { "assembly": { "type": "string" }, "chrom": { "type": "string" }, "pos": { "type": "integer", "format": "int64", "description": "1-based VCF position." }, "ref": { "type": "string" }, "alt": { "type": "string" } } }, "VrsTarget": { "type": "object", "required": [ "id", "object" ], "properties": { "id": { "type": "string", "description": "GA4GH computed identifier." }, "object": { "type": "object", "additionalProperties": true, "description": "VRS object returned by the translation service." } } }, "NormalizedVariant": { "type": "object", "required": [ "gene", "hgvs", "identifiers", "spdi", "vcf" ], "properties": { "gene": { "type": "string", "description": "Gene symbol, or an empty string when unavailable." }, "hgvs": { "type": "object", "required": [ "genome_grch38", "genome_grch37", "transcript", "protein" ], "properties": { "genome_grch38": { "type": "string", "description": "HGVS expression, or an empty string when unavailable." }, "genome_grch37": { "type": "string", "description": "HGVS expression, or an empty string when unavailable." }, "transcript": { "type": "string", "description": "HGVS expression, or an empty string when unavailable." }, "protein": { "type": "string", "description": "HGVS expression, or an empty string when unavailable." }, "genome_grch38_repeat": { "type": "string" }, "genome_grch37_repeat": { "type": "string" }, "transcript_representations": { "type": "array", "items": { "$ref": "#/components/schemas/HgvsRepresentation" } }, "protein_representations": { "type": "array", "items": { "$ref": "#/components/schemas/HgvsRepresentation" } } } }, "identifiers": { "type": "object", "required": [ "dbsnp", "clingen" ], "properties": { "dbsnp": { "type": "string", "description": "rsID or an empty string." }, "clingen": { "type": "string", "description": "CA ID or an empty string." } } }, "spdi": { "type": "string", "description": "SPDI expression with a 0-based inter-residue position, or an empty string." }, "vcf": { "type": "array", "items": { "$ref": "#/components/schemas/VcfRecord" } }, "vrs": { "type": "object", "description": "Computed VRS identifiers and objects, keyed by target (genome_grch38, genome_grch37, transcript or protein). Present when available from the translation service.", "additionalProperties": { "$ref": "#/components/schemas/VrsTarget" } }, "vrs_allele": { "type": "object", "additionalProperties": true, "description": "Fallback allele representation built from SPDI when computed VRS results are unavailable. Its sequence reference is a refseq: accession; it does not carry a computed GA4GH identifier." } } }, "InvalidVariant": { "type": "object", "required": [ "valid" ], "properties": { "valid": { "type": "boolean", "enum": [ false ] } }, "additionalProperties": false }, "VrsResult": { "type": "object", "required": [ "variants" ], "properties": { "variants": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/NormalizedVariant" }, { "$ref": "#/components/schemas/InvalidVariant" } ] } } }, "description": "SynVar normalisation wrapper, not a bare VRS Allele. An unrecognised input may produce an empty variants array. Recognised invalid variants can be represented by {\"valid\": false}." } }, "responses": { "VariantResult": { "description": "Reference examples are shown below. After Execute, your actual result appears under Server response.\n\nA 200 response means processing completed; inspect the body for empty results and validity/mapping information. Choose the output using the format parameter; the Media type dropdown below only sets the Accept header.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/LegacyJsonResult" }, { "$ref": "#/components/schemas/VrsResult" } ] }, "examples": { "brafVrs": { "summary": "BRAF V600E (format=vrs)", "description": "Example captured from a successful request; available references and identifiers may change.", "value": { "variants": [ { "gene": "BRAF", "hgvs": { "genome_grch38": "NC_000007.14:g.140753336A>T", "genome_grch37": "NC_000007.13:g.140453136A>T", "transcript": "NM_004333.6:c.1799T>A", "protein": "NP_004324.2:p.Val600Glu", "transcript_representations": [ { "type": "mane-select", "value": "NM_004333.6:c.1799T>A" }, { "type": "uniprot-canonical", "value": "NM_004333.6:c.1799T>A" } ], "protein_representations": [ { "type": "mane-select", "value": "NP_004324.2:p.Val600Glu" }, { "type": "uniprot-canonical", "value": "NP_004324.2:p.Val600Glu" } ] }, "identifiers": { "dbsnp": "rs113488022", "clingen": "CA123643" }, "spdi": "NC_000007.14:140753335:A:T", "vcf": [ { "assembly": "GRCh38", "chrom": "7", "pos": 140753336, "ref": "A", "alt": "T" }, { "assembly": "GRCh37", "chrom": "7", "pos": 140453136, "ref": "A", "alt": "T" } ], "vrs": { "genome_grch38": { "id": "ga4gh:VA.Otc5ovrw906Ack087o1fhegB4jDRqCAe", "object": { "id": "ga4gh:VA.Otc5ovrw906Ack087o1fhegB4jDRqCAe", "type": "Allele", "digest": "Otc5ovrw906Ack087o1fhegB4jDRqCAe", "location": { "id": "ga4gh:SL.nhul5x5P_fKjGEpY9PEkMIekJfZaKom2", "type": "SequenceLocation", "digest": "nhul5x5P_fKjGEpY9PEkMIekJfZaKom2", "sequenceReference": { "type": "SequenceReference", "refgetAccession": "SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul" }, "start": 140753335, "end": 140753336 }, "state": { "type": "LiteralSequenceExpression", "sequence": "T" } } }, "genome_grch37": { "id": "ga4gh:VA.nmp-bzYpO00NYIqr3CaVF0ZH2ZpSj1ly", "object": { "id": "ga4gh:VA.nmp-bzYpO00NYIqr3CaVF0ZH2ZpSj1ly", "type": "Allele", "digest": "nmp-bzYpO00NYIqr3CaVF0ZH2ZpSj1ly", "location": { "id": "ga4gh:SL.hVna-JOV5bBTGdXexL--IQm135MG3bGT", "type": "SequenceLocation", "digest": "hVna-JOV5bBTGdXexL--IQm135MG3bGT", "sequenceReference": { "type": "SequenceReference", "refgetAccession": "SQ.IW78mgV5Cqf6M24hy52hPjyyo5tCCd86" }, "start": 140453135, "end": 140453136 }, "state": { "type": "LiteralSequenceExpression", "sequence": "T" } } }, "transcript": { "id": "ga4gh:VA.W6xsV-aFm9yT2Bic5cFAV2j0rll6KK5R", "object": { "id": "ga4gh:VA.W6xsV-aFm9yT2Bic5cFAV2j0rll6KK5R", "type": "Allele", "digest": "W6xsV-aFm9yT2Bic5cFAV2j0rll6KK5R", "location": { "id": "ga4gh:SL.8HBKs9fzlT3tKWlM03REjkg_0Om6Y33U", "type": "SequenceLocation", "digest": "8HBKs9fzlT3tKWlM03REjkg_0Om6Y33U", "sequenceReference": { "type": "SequenceReference", "refgetAccession": "SQ.aKMPEJgmlZXt_F6gRY5cUG3THH2n-GUa" }, "start": 2024, "end": 2025 }, "state": { "type": "LiteralSequenceExpression", "sequence": "A" } } }, "protein": { "id": "ga4gh:VA.j4XnsLZcdzDIYa5pvvXM7t1wn9OITr0L", "object": { "id": "ga4gh:VA.j4XnsLZcdzDIYa5pvvXM7t1wn9OITr0L", "type": "Allele", "digest": "j4XnsLZcdzDIYa5pvvXM7t1wn9OITr0L", "location": { "id": "ga4gh:SL.t-3DrWALhgLdXHsupI-e-M00aL3HgK3y", "type": "SequenceLocation", "digest": "t-3DrWALhgLdXHsupI-e-M00aL3HgK3y", "sequenceReference": { "type": "SequenceReference", "refgetAccession": "SQ.cQvw4UsHHRRlogxbWCB8W-mKD4AraM9y" }, "start": 599, "end": 600 }, "state": { "type": "LiteralSequenceExpression", "sequence": "E" } } } } } ] } }, "emptyVrs": { "summary": "No result (format=vrs)", "value": { "variants": [] } }, "invalidVrs": { "summary": "Recognised invalid variant (format=vrs)", "value": { "variants": [ { "valid": false } ] } }, "emptyJson": { "summary": "No result (format=json)", "value": {} } } }, "application/xml": { "schema": { "type": "string" }, "example": "" } } }, "BadRequest": { "description": "Missing variant parameter or malformed HTTP request. Error responses are not guaranteed to use the selected format." }, "ServerError": { "description": "Unexpected server error. Error responses are not guaranteed to use the selected format." } } } }