Forge Tools dbsnp

dbsnp read

scidex.forge.dbsnp

Look up canonical variant metadata from NCBI dbSNP for one or more rsIDs. Returns variant type (SNP/INDEL/MNV), ref/alt alleles (GRCh38), chromosomal position (GRCh38, 1-based), gene context with SO consequence terms, multi-population allele frequencies (gnomAD/1000G/TOPMED/ESP), ClinVar clinical significance, and merge history. Up to 20 rsIDs per call; fetched with up to 5 concurrent requests. Not-found rsIDs go to the not_found list — not an exception. REST API: https://api.ncbi.nlm.nih.gov/variation/v0 — free, no auth required.

HTTP: POST /api/scidex/forge/dbsnp

Invoke

Calls scidex.tool.invoke on the substrate with this tool name. Edit the JSON below — it must match the input schema. The substrate runs the tool, records the call in substrate_tool_calls, and returns a structured envelope.

Sign in to invoke this tool. Schema and curl snippet are visible to anyone.

Schemas

Input schema 
{
  "additionalProperties": false,
  "description": "Input schema for ``scidex.forge.dbsnp``.",
  "properties": {
    "rsids": {
      "description": "List of dbSNP rsIDs to look up (e.g. [\"rs699\", \"rs429358\"]). Maximum 20 rsIDs per call. Each must start with 'rs' followed by one or more digits (case-insensitive).",
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "minItems": 1,
      "title": "Rsids",
      "type": "array"
    },
    "include_frequency": {
      "default": true,
      "description": "If True (default), include multi-population allele frequencies in each variant. Set False to reduce response size when frequencies are not needed.",
      "title": "Include Frequency",
      "type": "boolean"
    },
    "include_gene_context": {
      "default": true,
      "description": "If True (default), include gene context annotations in each variant. Set False to reduce response size when gene context is not needed.",
      "title": "Include Gene Context",
      "type": "boolean"
    }
  },
  "required": [
    "rsids"
  ],
  "title": "ForgeDBSNPIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "AlleleFrequency": {
      "description": "Allele frequency from one population study.",
      "properties": {
        "study_name": {
          "description": "Study/population name (e.g. GnomAD, 1000Genomes, TOPMED, ESP6500).",
          "title": "Study Name",
          "type": "string"
        },
        "allele_count": {
          "default": 0,
          "description": "Alternate allele observation count.",
          "title": "Allele Count",
          "type": "integer"
        },
        "total_count": {
          "default": 0,
          "description": "Total allele count in the cohort.",
          "title": "Total Count",
          "type": "integer"
        },
        "allele_frequency": {
          "default": 0,
          "description": "Allele frequency as a fraction in [0.0, 1.0] (allele_count / total_count).",
          "title": "Allele Frequency",
          "type": "number"
        }
      },
      "required": [
        "study_name"
      ],
      "title": "AlleleFrequency",
      "type": "object"
    },
    "DBSNPVariant": {
      "description": "One dbSNP canonical variant record.",
      "properties": {
        "rsid": {
          "description": "dbSNP reference SNP ID (e.g. rs699).",
          "title": "Rsid",
          "type": "string"
        },
        "variant_type": {
          "default": "",
          "description": "Variant type from dbSNP: snv, mnv, del, ins, indel, microsatellite, etc.",
          "title": "Variant Type",
          "type": "string"
        },
        "ref_allele": {
          "default": "",
          "description": "Reference allele sequence (GRCh38).",
          "title": "Ref Allele",
          "type": "string"
        },
        "alt_alleles": {
          "description": "Alternate allele sequences (GRCh38). Multi-allelic variants may have more than one.",
          "items": {
            "type": "string"
          },
          "title": "Alt Alleles",
          "type": "array"
        },
        "chromosome": {
          "default": "",
          "description": "Chromosome name (e.g. '1', '22', 'X', 'Y', 'MT'). Empty if no GRCh38 placement available.",
          "title": "Chromosome",
          "type": "string"
        },
        "position_grch38": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "1-based chromosomal position on GRCh38. None when no GRCh38 top-level placement is available.",
          "title": "Position Grch38"
        },
        "gene_context": {
          "description": "Gene annotations and SO consequence terms at this locus.",
          "items": {
            "$ref": "#/$defs/GeneContext"
          },
          "title": "Gene Context",
          "type": "array"
        },
        "allele_frequencies": {
          "description": "Multi-population allele frequencies from gnomAD, 1000 Genomes, TOPMED, ESP, and other studies indexed by dbSNP.",
          "items": {
            "$ref": "#/$defs/AlleleFrequency"
          },
          "title": "Allele Frequencies",
          "type": "array"
        },
        "clinical_significance": {
          "description": "ClinVar clinical significance values for this variant (e.g. Pathogenic, Likely pathogenic, Uncertain significance, Benign).",
          "items": {
            "type": "string"
          },
          "title": "Clinical Significance",
          "type": "array"
        },
        "merged_into": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "rsID of the surviving SNP if this rsID was merged (e.g. 'rs123456'). None if the rsID is current.",
          "title": "Merged Into"
        }
      },
      "required": [
        "rsid"
      ],
      "title": "DBSNPVariant",
      "type": "object"
    },
    "GeneContext": {
      "description": "Gene context annotation for a variant locus.",
      "properties": {
        "symbol": {
          "description": "HGNC gene symbol (e.g. AGT, BRCA1).",
          "title": "Symbol",
          "type": "string"
        },
        "name": {
          "default": "",
          "description": "Gene full name / locus description.",
          "title": "Name",
          "type": "string"
        },
        "gene_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "NCBI Gene ID.",
          "title": "Gene Id"
        },
        "consequences": {
          "description": "Sequence Ontology consequence terms for this gene (e.g. missense_variant, intron_variant, 3_prime_UTR_variant, intergenic_variant).",
          "items": {
            "type": "string"
          },
          "title": "Consequences",
          "type": "array"
        }
      },
      "required": [
        "symbol"
      ],
      "title": "GeneContext",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.dbsnp``.",
  "properties": {
    "variants": {
      "description": "Variant records for found rsIDs (order matches the input rsids list).",
      "items": {
        "$ref": "#/$defs/DBSNPVariant"
      },
      "title": "Variants",
      "type": "array"
    },
    "not_found": {
      "description": "rsIDs that were not found in dbSNP (404 or withdrawn).",
      "items": {
        "type": "string"
      },
      "title": "Not Found",
      "type": "array"
    },
    "took_ms": {
      "description": "Wall-clock time for all upstream API calls.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "took_ms"
  ],
  "title": "ForgeDBSNPOut",
  "type": "object"
}

curl snippet

Replace $SCIDEX_JWT with a valid bearer token. Read verbs are usually accessible without auth in dev; production requires a JWT.

curl -sS -X POST '/api/scidex/forge/dbsnp' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "rsids": []
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.