Forge Tools cosmic_mutations

cosmic_mutations read

scidex.forge.cosmic_mutations

Look up somatic cancer mutations in the COSMIC database for 1–5 genes. Returns COSV/COSM mutation IDs, amino acid changes (e.g. p.V600E), tumour types, sample counts, COSMIC tier, and Census driver classification. Complements ClinVar (germline) and gnomAD (population AF) with somatic tumour data. Set COSMIC_API_KEY env var for higher rate limits.

HTTP: POST /api/scidex/forge/cosmic_mutations

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.cosmic_mutations``.",
  "properties": {
    "gene_symbols": {
      "description": "HGNC gene symbols to query (e.g. ``['BRAF', 'BRCA2']``). Accepts 1–5 genes. Results are aggregated across all genes.",
      "items": {
        "type": "string"
      },
      "maxItems": 5,
      "minItems": 1,
      "title": "Gene Symbols",
      "type": "array"
    },
    "cancer_type": {
      "anyOf": [
        {
          "maxLength": 128,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional tumour-type filter (case-insensitive substring match on ``cancer_types``). E.g. ``'breast'``, ``'lung'``. Only mutations observed in a matching tumour type are returned.",
      "title": "Cancer Type"
    },
    "limit": {
      "default": 20,
      "description": "Maximum mutations to return per gene (default 20, max 200).",
      "maximum": 200,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "gene_symbols"
  ],
  "title": "ForgeCosmicIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "CosmicMutation": {
      "description": "One somatic mutation record from COSMIC.",
      "properties": {
        "gene_symbol": {
          "description": "HGNC gene symbol.",
          "title": "Gene Symbol",
          "type": "string"
        },
        "mutation_id": {
          "description": "COSMIC mutation accession (COSV or COSM ID).",
          "title": "Mutation Id",
          "type": "string"
        },
        "aa_mutation": {
          "default": "",
          "description": "Amino acid change (e.g. ``p.V600E``). Empty when non-coding.",
          "title": "Aa Mutation",
          "type": "string"
        },
        "cds_mutation": {
          "default": "",
          "description": "Coding-sequence change (e.g. ``c.1799T>A``).",
          "title": "Cds Mutation",
          "type": "string"
        },
        "cancer_types": {
          "description": "Tumour types in which this mutation has been observed.",
          "items": {
            "type": "string"
          },
          "title": "Cancer Types",
          "type": "array"
        },
        "sample_count": {
          "default": 0,
          "description": "Number of tumour samples carrying this mutation in COSMIC.",
          "minimum": 0,
          "title": "Sample Count",
          "type": "integer"
        },
        "cosmic_tier": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "COSMIC Census tier: 1=hallmark oncogene/TSG, 2=candidate driver. None when not in Census.",
          "title": "Cosmic Tier"
        },
        "is_driver": {
          "default": false,
          "description": "True when the gene is classified as a driver in the COSMIC Cancer Gene Census.",
          "title": "Is Driver",
          "type": "boolean"
        }
      },
      "required": [
        "gene_symbol",
        "mutation_id"
      ],
      "title": "CosmicMutation",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.cosmic_mutations``.",
  "properties": {
    "mutations": {
      "description": "Somatic mutation records ordered by descending sample_count within each gene. Empty when the gene is unknown to COSMIC.",
      "items": {
        "$ref": "#/$defs/CosmicMutation"
      },
      "title": "Mutations",
      "type": "array"
    },
    "genes_queried": {
      "description": "Number of gene symbols queried (not necessarily all with results).",
      "title": "Genes Queried",
      "type": "integer"
    },
    "took_ms": {
      "default": 0,
      "description": "Wall-clock time for all upstream COSMIC API calls.",
      "title": "Took Ms",
      "type": "integer"
    }
  },
  "required": [
    "genes_queried"
  ],
  "title": "ForgeCosmicOut",
  "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/cosmic_mutations' \
  -H 'authorization: Bearer $SCIDEX_JWT' \
  -H 'content-type: application/json' \
  -d '{
  "gene_symbols": []
}'

Discussion

Posting anonymously. Sign in for attribution.

No comments yet — be the first.