Forge Tools cbioportal_mutations

cbioportal_mutations read

scidex.forge.cbioportal_mutations

Look up somatic mutations in cBioPortal (300+ cancer studies) for 1–10 genes. Returns per-sample mutation records (mutation type, protein change, genomic coordinates, functional impact) and per-study frequency summaries. Optionally restrict to specific study IDs or mutation types. No API key required. Invalid study_ids raise a ToolError.

HTTP: POST /api/scidex/forge/cbioportal_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.cbioportal_mutations``.",
  "properties": {
    "gene_symbols": {
      "description": "HGNC gene symbols to query (e.g. ``['TP53', 'KRAS']``). Accepts 1–10 genes. Mutations are fetched in a single POST request.",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "minItems": 1,
      "title": "Gene Symbols",
      "type": "array"
    },
    "study_ids": {
      "description": "Optional list of cBioPortal study IDs to restrict the query (e.g. ``['tcga_brca', 'tcga_luad']``). When empty, all public studies are queried (slower). Invalid study IDs raise a ToolError.",
      "items": {
        "type": "string"
      },
      "title": "Study Ids",
      "type": "array"
    },
    "mutation_types": {
      "description": "Optional mutation-type filter (case-sensitive). Examples: 'Missense_Mutation', 'Nonsense_Mutation', 'Frame_Shift_Del', 'Splice_Site', 'Frame_Shift_Ins'. When empty, all types are returned.",
      "items": {
        "type": "string"
      },
      "title": "Mutation Types",
      "type": "array"
    },
    "limit": {
      "default": 50,
      "description": "Maximum number of mutation records to return (default 50, max 500).",
      "maximum": 500,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "gene_symbols"
  ],
  "title": "ForgeCBioPortalIn",
  "type": "object"
}
Output schema 
{
  "$defs": {
    "CBioMutation": {
      "description": "One somatic mutation record from cBioPortal.",
      "properties": {
        "study_id": {
          "description": "cBioPortal study identifier (e.g. 'tcga_brca').",
          "title": "Study Id",
          "type": "string"
        },
        "sample_id": {
          "description": "Sample (patient tumour) identifier.",
          "title": "Sample Id",
          "type": "string"
        },
        "gene_symbol": {
          "description": "HGNC gene symbol.",
          "title": "Gene Symbol",
          "type": "string"
        },
        "mutation_type": {
          "description": "Mutation consequence type, e.g. 'Missense_Mutation', 'Nonsense_Mutation', 'Frame_Shift_Del', 'Splice_Site', 'Frame_Shift_Ins'.",
          "title": "Mutation Type",
          "type": "string"
        },
        "protein_change": {
          "default": "",
          "description": "Protein-level change in HGVS-like notation (e.g. 'p.R175H'). Empty when non-coding.",
          "title": "Protein Change",
          "type": "string"
        },
        "chromosome": {
          "default": "",
          "description": "Chromosome (e.g. '17', 'X').",
          "title": "Chromosome",
          "type": "string"
        },
        "start_position": {
          "default": 0,
          "description": "1-based genomic start position.",
          "title": "Start Position",
          "type": "integer"
        },
        "ref_allele": {
          "default": "",
          "description": "Reference allele (e.g. 'C').",
          "title": "Ref Allele",
          "type": "string"
        },
        "var_allele": {
          "default": "",
          "description": "Variant/tumour allele (e.g. 'T').",
          "title": "Var Allele",
          "type": "string"
        },
        "functional_impact": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Predicted functional impact score from tools such as SIFT, PolyPhen, or IMPACT (HIGH/MODERATE/LOW). None when not annotated.",
          "title": "Functional Impact"
        }
      },
      "required": [
        "study_id",
        "sample_id",
        "gene_symbol",
        "mutation_type"
      ],
      "title": "CBioMutation",
      "type": "object"
    },
    "StudyMutFreq": {
      "description": "Per-study mutation frequency summary.",
      "properties": {
        "study_id": {
          "description": "cBioPortal study identifier.",
          "title": "Study Id",
          "type": "string"
        },
        "study_name": {
          "description": "Human-readable study name.",
          "title": "Study Name",
          "type": "string"
        },
        "cancer_type": {
          "description": "Cancer type label (e.g. 'Breast Invasive Carcinoma').",
          "title": "Cancer Type",
          "type": "string"
        },
        "mutated_samples": {
          "description": "Number of samples carrying at least one mutation in the queried genes.",
          "minimum": 0,
          "title": "Mutated Samples",
          "type": "integer"
        },
        "total_samples": {
          "description": "Total samples profiled in the study.",
          "minimum": 0,
          "title": "Total Samples",
          "type": "integer"
        },
        "frequency": {
          "description": "Fraction of profiled samples with a mutation (mutated_samples / total_samples).",
          "maximum": 1,
          "minimum": 0,
          "title": "Frequency",
          "type": "number"
        }
      },
      "required": [
        "study_id",
        "study_name",
        "cancer_type",
        "mutated_samples",
        "total_samples",
        "frequency"
      ],
      "title": "StudyMutFreq",
      "type": "object"
    }
  },
  "description": "Response shape for ``scidex.forge.cbioportal_mutations``.",
  "properties": {
    "mutations": {
      "description": "Somatic mutation records, ordered as returned by cBioPortal. Empty when no mutations are found for the queried genes.",
      "items": {
        "$ref": "#/$defs/CBioMutation"
      },
      "title": "Mutations",
      "type": "array"
    },
    "study_summary": {
      "description": "Per-study mutation frequency aggregates derived from the returned mutations. Each entry shows how many samples in that study carry at least one mutation in the queried genes.",
      "items": {
        "$ref": "#/$defs/StudyMutFreq"
      },
      "title": "Study Summary",
      "type": "array"
    }
  },
  "title": "ForgeCBioPortalOut",
  "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/cbioportal_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.