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

{
  "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

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.

{
  "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

{
  "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.

{
  "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

{
  "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

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.

PreviousArchitecture NextAPI Benchmark

Last updated 1 month ago

Was this helpful?

Introduction

Authentication

OncoKB™ Instances

https://www.oncokb.org

https://demo.oncokb.org

Annotation API Examples

Annotate Mutations by Protein Change

Query Parameters

Headers

Curl Example

www.oncokb

demo.oncokb

Typical Use Cases

Missense mutation in an oncogene: BRAF, V600E, Melanoma

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

In-frame deletion: BRAF, N486_P490del, Histiocytosis

Fusion: ROS1, CD74-ROS1 fusion, Lung Adenocarcinoma

Atypical Alterations

Annotate Copy Number Alterations

Query Parameters

Headers

Curl Example

Annotate Structural Variants

Query Parameters

Headers

Curl Example

Annotate Mutations by Genomic Change

Query Parameters

Headers

Curl Example

Annotate Mutations by HGVSg

Query Parameters

Headers

Curl Example

API Changelog