API

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

NameTypeDescription

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

NameTypeDescription

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

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

referenceGenome

string

Either GRCh37 or GRCh38. The default is GRCh37.

genomicaLocation

string

Genomic location. 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

NameTypeDescription

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

NameTypeDescription

referenceGenome

string

Either GRCh37 or GRCh38. The default is GRCh37.

hgvsg

string

HGVS genomic format. 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

NameTypeDescription

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

PreviousArchitectureNextVariant Annotators

Last updated