API Info

Introduction

The OncoKB™ data can be accessed through a REST API (Swagger Page). The API is defined and organized using swagger annotation. MAF file annotation is also possible by using OncoKB™ Annotator which is fully supported by using OncoKB™ REST APIs.

When you send API requests, you need a token before accessing the OncoKB™ data via its web API. Please visit OncoKB™ Data Access Page for more information about how to register an account and get an OncoKB™ API token.

Authentication

We are using standard Spring Security to protect all our services. In order to access the OncoKB™ data via its REST API, you need to specify your API token in the request header with

Authorization: Bearer [your token]

Your token will be available under your Account Settings after getting a license from the OncoKB™ Team.

OncoKB™ Instances

https://www.oncokb.org

This is the main instance and authenticated. If you have gotten a license from OncoKB™. Please use this instance for most accurate results.

https://demo.oncokb.org

Before committing to our license, you can use this website to test the API and other services freely. We included the full information of BRAF, TP53 and ROS1. The instance is not authenticated.

Annotation API Examples

If you have the access token and like to play around with our endpoints, please see the Swagger page. We only list GET methods here. They all have corresponding POST method available. Please see the Swagger page for more details.

Annotate Mutations by Protein Change

GET https://www.oncokb.org/api/v1/annotate/mutations/byProteinChange

Query Parameters

Name	Type	Description
referenceGenome	string	Either GRCh37 or GRCh38. The default is GRCh37.
hugoSymbol	string	The gene symbol used in Human Genome Organization. Example: BRAF
entrezGeneId	integer	The entrez gene ID. (Higher priority than hugoSymbol). Example: 673
alteration	string	Protein Change. Example: V600E
consequence	string	Consequence. Example: missense_variant
proteinStart	integer	Protein Start. Example: 600
proteinEnd	integer	Protein End. Example: 600
tumorType	string	OncoTree(http://oncotree.mskcc.org) tumor type name. The field supports OncoTree Code, OncoTree Name and OncoTree Main type. Example: Melanoma

Headers

Name	Type	Description
Authentication	string	OncoKB Token

200 Annotate mutations by protein change successfully.

{
  "query": {
    "id": null,
    "type": "regular",
    "hugoSymbol": "BRAF",
    "entrezGeneId": 673,
    "alteration": "V600E",
    "alterationType": null,
    "svType": null,
    "tumorType": "Melanoma",
    "consequence": "missense_variant",
    "proteinStart": 600,
    "proteinEnd": 600,
    "hgvs": null
  },
  "geneExist": true,
  "variantExist": true,
  "alleleExist": true,
  "oncogenic": "Predicted Oncogenic",
  "mutationEffect": {
    "knownEffect": "Unknown",
    "description": "",
    "citations": {
      "pmids": [],
      "abstracts": []
    }
  },
  "highestSensitiveLevel": null,
  "highestResistanceLevel": null,
  "highestDiagnosticImplicationLevel": null,
  "highestPrognosticImplicationLevel": null,
  "otherSignificantSensitiveLevels": [],
  "otherSignificantResistanceLevels": [],
  "hotspot": true,
  "geneSummary": "BRAF, an intracellular kinase, is frequently mutated in melanoma, thyroid and lung cancers among others.",
  "variantSummary": "The BRAF V600E mutation is known to be oncogenic.",
  "tumorTypeSummary": "",
  "prognosticSummary": "",
  "diagnosticSummary": "",
  "diagnosticImplications": null,
  "prognosticImplications": null,
  "treatments": [],
  "dataVersion": "v2.1",
  "lastUpdate": "06/04/2018",
  "vus": false
}

Curl Example

www.oncokb

curl -X GET "https://www.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF&alteration=V600E&tumorType=Melanoma" -H "accept: application/json" -H "Authorization: Bearer [your personal token]"

demo.oncokb

curl -X GET "https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF&alteration=V600E&tumorType=Melanom"  -H "accept: application/json"

Typical Use Cases

Missense mutation in an oncogene: BRAF, V600E, Melanoma

https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF&alteration=V600E&tumorType=Melanom

Missense mutation in a tumor suppressor: TP53, R273C, Colon Adenocarcinoma

https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=TP53&alteration=R273C&tumorType=Colon%20Adenocarcinoma

In-frame deletion: BRAF, N486_P490del, Histiocytosis

https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF&alteration=N486_P490del&tumorType=Histiocytosis

Fusion: ROS1, CD74-ROS1 fusion, Lung Adenocarcinoma

https://demo.oncokb.org/api/v1/annotate/structuralVariants?hugoSymbolA=CD74&hugoSymbolB=ROS1&structuralVariantType=FUSION&isFunctionalFusion=true&tumorType=Lung%20Adenocarcinoma

Atypical Alterations

For atypical alterations, please also use this endpoint. For instance, but not limited to

• vII

• vIII

• vV

• CTD or C-terminal domain

• KDD or Kinase Domain Duplication

• ITD or Internal Tandem Duplication

• MSI-H or Microsatellite Instability-High

• TMB-H or Tumor Mutational Burden-High

Demo site does not have atypical alteration. Please use your authentication token for the following examples

EGFR vIII

curl -X 'GET' \
  'https://www.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=EGFR&alteration=vIII' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [your token]'

MSI-H

curl -X 'GET' \
  'https://www.oncokb.org/api/v1/annotate/mutations/byProteinChange?alteration=MSI-H' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [your token]'

Annotate Copy Number Alterations

GET https://www.oncokb.org/api/v1/annotate/copyNumberAlterations

Query Parameters

Name	Type	Description
referenceGenome	string	Either GRCh37 or GRCh38. Default is GRCh37.
copyNameAlterationType	string	Copy number alteration type. Available types: AMPLIFICATION, DELETION, GAIN, LOSS.
entrezGeneId	integer	The entrez gene ID. (Higher priority than hugoSymbol). Example: 673.
hugoSymbol	string	The gene symbol used in Human Genome Organization. Example: BRAF.
tumorType	string	OncoTree(http://oncotree.mskcc.org) tumor type name. The field supports OncoTree Code, OncoTree Name and OncoTree Main type. Example: Melanoma.

Headers

Name	Type	Description
Authentication	string	OncoKB Token provided by OncoKB website to registered and approved users.

200 Annotate copy number alterations successfully.

{
  "query": {
    "id": null,
    "type": "regular",
    "hugoSymbol": "BRAF",
    "entrezGeneId": 673,
    "alteration": "Amplification",
    "alterationType": null,
    "svType": null,
    "tumorType": "melanoma",
    "consequence": null,
    "proteinStart": null,
    "proteinEnd": null,
    "hgvs": null
  },
  "geneExist": true,
  "variantExist": true,
  "alleleExist": false,
  "oncogenic": "Oncogenic",
  "mutationEffect": {
    "knownEffect": "Gain-of-function",
    "description": "",
    "citations": {
      "pmids": [
        "24055054",
        "25618114",
        "22395615",
        "21098728",
        "15467732"
      ],
      "abstracts": []
    }
  },
  "highestSensitiveLevel": null,
  "highestResistanceLevel": null,
  "highestDiagnosticImplicationLevel": null,
  "highestPrognosticImplicationLevel": null,
  "otherSignificantSensitiveLevels": [],
  "otherSignificantResistanceLevels": [],
  "hotspot": false,
  "geneSummary": "BRAF, an intracellular kinase, is frequently mutated in melanoma, thyroid and lung cancers among others.",
  "variantSummary": "BRAF amplification is known to be oncogenic.",
  "tumorTypeSummary": "There are no FDA-approved or NCCN-compendium listed treatments specifically for patients with BRAF-amplified melanoma.",
  "prognosticSummary": "",
  "diagnosticSummary": "",
  "diagnosticImplications": [],
  "prognosticImplications": [],
  "treatments": [],
  "dataVersion": "v2.1",
  "lastUpdate": "07/20/2019",
  "vus": false
}

Curl Example

curl -X GET "https://www.oncokb.org/api/v1/annotate/copyNumberAlterations?hugoSymbol=BRAF&copyNameAlterationType=AMPLIFICATION&tumorType=MEL" -H "accept: application/json" -H "Authorization: Bearer [your personal token]"

Annotate Structural Variants

GET ttps://www.oncokb.org/api/v1/annotate/structuralVariants

Query Parameters

Name	Type	Description
referenceGenome	string	Either GRCh37 or GRCh38. The default is GRCh37.
structuralVariantType	string	Structural variant type Available values : DELETION, TRANSLOCATION, DUPLICATION, INSERTION, INVERSION, FUSION, UNKNOWN
isFunctionalFusion	boolean	Whether is functional fusion. Default value: false.
hugoSymbolA	string	The gene symbol A used in Human Genome Organization. Example: ABL1
entrezGeneIdA	integer	The entrez gene ID A. (Higher priority than hugoSymbolA) Example: 25
hugoSymbolB	string	The gene symbol B used in Human Genome Organization. Example: BCR
entrezGeneIdB	integer	The entrez gene ID B. (Higher priority than hugoSymbolB) Example: 613
tumorType	string	OncoTree(http://oncotree.mskcc.org) tumor type name. The field supports OncoTree Code, OncoTree Name and OncoTree Main type. Example: Melanoma

Headers

Name	Type	Description
Authentication	string	OncoKB Token

200 Annotate structural variants successfully.

{
  "query": {
    "id": null,
    "type": "regular",
    "hugoSymbol": "ABL1",
    "entrezGeneId": 25,
    "alteration": "truncating mutation",
    "alterationType": "STRUCTURAL_VARIANT",
    "svType": "DELETION",
    "tumorType": "Melanoma",
    "consequence": "feature_truncation",
    "proteinStart": null,
    "proteinEnd": null,
    "hgvs": null
  },
  "geneExist": true,
  "variantExist": false,
  "alleleExist": false,
  "oncogenic": "",
  "mutationEffect": {
    "knownEffect": "Unknown",
    "description": "",
    "citations": {
      "pmids": [],
      "abstracts": []
    }
  },
  "highestSensitiveLevel": null,
  "highestResistanceLevel": null,
  "highestDiagnosticImplicationLevel": null,
  "highestPrognosticImplicationLevel": null,
  "otherSignificantSensitiveLevels": [],
  "otherSignificantResistanceLevels": [],
  "hotspot": false,
  "geneSummary": "",
  "variantSummary": "",
  "tumorTypeSummary": "",
  "prognosticSummary": "",
  "diagnosticSummary": "",
  "diagnosticImplications": null,
  "prognosticImplications": null,
  "treatments": [],
  "dataVersion": "v2.1",
  "lastUpdate": "02/12/2020",
  "vus": false
}

Curl Example

curl -X GET "https://www.oncokb.org/api/v1/annotate/structuralVariants?hugoSymbolA=ABL1&hugoSymbolB=BCR&structuralVariantType=DELETION&isFunctionalFusion=true&tumorType=Melanoma" -H "accept: application/json" -H "Authorization: Bearer [your personal token]"

Annotate Mutations by Genomic Change

GET https://www.oncokb.org/api/v1/annotate/mutations/byGenomicChange

Query Parameters

Name	Type	Description
referenceGenome	string	Either GRCh37 or GRCh38. The default is GRCh37.
genomicLocation	string	Genomic location following TCGA MAF format. Example: 7,140453136,140453136,A,T
tumorType	string	OncoTree(http://oncotree.mskcc.org) tumor type name. The field supports OncoTree Code, OncoTree Name and OncoTree Main type. Example: Melanoma

Headers

Name	Type	Description
Authencitation	string	OncoKB token.

200 Annotated mutations by genomic change successfully.

{
  "query": {
    "id": null,
    "type": "regular",
    "hugoSymbol": "BRAF",
    "entrezGeneId": 673,
    "alteration": "V600E",
    "alterationType": null,
    "svType": null,
    "tumorType": "Melanoma",
    "consequence": "missense_variant",
    "proteinStart": 600,
    "proteinEnd": 600,
    "hgvs": null
  },
  "geneExist": true,
  "variantExist": true,
  "alleleExist": true,
  "oncogenic": "Oncogenic",
  "mutationEffect": {
    "knownEffect": "Unknown",
    "description": "",
    "citations": {
      "pmids": [],
      "abstracts": []
    }
  },
  "highestSensitiveLevel": null,
  "highestResistanceLevel": null,
  "highestDiagnosticImplicationLevel": null,
  "highestPrognosticImplicationLevel": null,
  "otherSignificantSensitiveLevels": [],
  "otherSignificantResistanceLevels": [],
  "hotspot": true,
  "geneSummary": "",
  "variantSummary": "",
  "tumorTypeSummary": "",
  "prognosticSummary": "",
  "diagnosticSummary": "",
  "diagnosticImplications": null,
  "prognosticImplications": null,
  "treatments": [],
  "dataVersion": "v2.1",
  "lastUpdate": "04/24/2017",
  "vus": false
}

Curl Example

curl -X GET "https://www.oncokb.org/api/v1/annotate/mutations/byGenomicChange?genomicLocation=7%2C140453136%2C140453136%2CA%2CT&tumorType=Melanoma" -H "accept: application/json" -H "Authorization: Bearer [your personal token]"

Annotate Mutations by HGVSg

GET ttps://www.oncokb.org/api/v1/annotate/mutations/byHGVSg

Query Parameters

Name	Type	Description
referenceGenome	string	Either GRCh37 or GRCh38. The default is GRCh37.
hgvsg	string	HGVS genomic format following HGVS nomenclature. Example: 7:g.140453136A>T
tumorType	string	OncoTree(http://oncotree.mskcc.org) tumor type name. The field supports OncoTree Code, OncoTree Name and OncoTree Main type. Example: Melanoma

Headers

Name	Type	Description
Authentication	string	OncoKB Token

200 Annotate mutations by HGVSg successfully.

{
  "query": {
    "id": null,
    "type": "regular",
    "hugoSymbol": null,
    "entrezGeneId": null,
    "alteration": "",
    "alterationType": null,
    "svType": null,
    "tumorType": "Melanoma",
    "consequence": null,
    "proteinStart": null,
    "proteinEnd": null,
    "hgvs": "g.140453136A>T"
  },
  "geneExist": false,
  "variantExist": null,
  "alleleExist": null,
  "oncogenic": "",
  "mutationEffect": {
    "knownEffect": "Unknown",
    "description": "",
    "citations": {
      "pmids": [],
      "abstracts": []
    }
  },
  "highestSensitiveLevel": null,
  "highestResistanceLevel": null,
  "highestDiagnosticImplicationLevel": null,
  "highestPrognosticImplicationLevel": null,
  "otherSignificantSensitiveLevels": [],
  "otherSignificantResistanceLevels": [],
  "hotspot": null,
  "geneSummary": "",
  "variantSummary": "",
  "tumorTypeSummary": "",
  "prognosticSummary": "",
  "diagnosticSummary": "",
  "diagnosticImplications": null,
  "prognosticImplications": null,
  "treatments": [],
  "dataVersion": "v2.1",
  "lastUpdate": "02/12/2020",
  "vus": null
}

Curl Example

curl -X GET "https://www.oncokb.org/api/v1/annotate/mutations/byHGVSg?hgvsg=7g.140453136A%3ET&tumorType=Melanoma" -H "accept: application/json" -H "Authorization: Bearer [your personal token]"

API Changelog

1. The evidenceTypefield is not recommended for use in any OncoKB software version. As of v3.24.0, we are marking the field as deprecated and will be removed in the near future.