Written and maintained by CASRAI Editorial Board
Last updated
General information for researchers and laboratory staff. This page does not give medical advice and does not tell any patient which treatment to use.
Short answer
OncoKB is a precision oncology knowledge base developed at Memorial Sloan Kettering Cancer Center (MSK). It classifies cancer gene variants by whether they are oncogenic and assigns tumor-type-specific evidence levels. It can be used through the website, a REST API that needs an access token, or the OncoKB Annotator scripts that add its annotations to variant files.
Definition and scope
OncoKB is described in its founding paper, Chakravarty et al., “OncoKB: A Precision Oncology Knowledge Base,” JCO Precision Oncology, November 2017 (DOI 10.1200/PO.17.00011). MSK’s David Solit has summarised its purpose as a tool “to help doctors understand which mutations in a particular gene are important.”
In October 2021 the US Food and Drug Administration granted OncoKB partial recognition as a genetic variant database, which MSK described as the first such recognition. The scope matters: according to MSK, the recognition covers how OncoKB classifies variants as drivers and assigns tumor-type-specific classifications and evidence levels. It does not cover the targeted drugs listed on the OncoKB website (MSK news release, 4 November 2021, read 8 November 2026).
How OncoKB is used in practice
Evidence levels (OncoKB levels)
Per MSK’s description, Level 1 is an FDA-recognized biomarker predictive of response to an FDA-approved drug, and Level 2 is a biomarker widely accepted as standard of care for an FDA-approved drug. Levels 1 and 2 are used to match patients with approved targeted drugs. Levels 3 and 4 mark evidence that is still being studied and may suggest candidacy for a clinical trial. Because levels are assigned per tumor type, the same variant can carry different levels in different cancers.
OncoKB API
OncoKB states that its data can be accessed through the OncoKB REST API, with the full reference on a Swagger page. Requests use a bearer token that is available in Account Settings after an account is approved. The token should be kept private, and it determines which licensed data your requests can access. The public instance returns all genes excluding therapeutic data, and a demo instance returns full data for BRAF, TP53 and ROS1 (OncoKB API page, read 8 November 2026).
OncoKB Annotator
The open-source OncoKB Annotator on GitHub annotates variants in MAF files with OncoKB annotation. It includes separate scripts for mutations (MafAnnotator.py, with vcf2maf as the route from VCF), copy number alterations (CnaAnnotator.py, GISTIC 2.0 format by default), fusions (FusionAnnotator.py), structural variants (StructuralVariantAnnotator.py) and merging results into clinical data (ClinicalDataAnnotator.py). The mutation, fusion and copy-number scripts need an API token passed with the -b option. Output columns include ANNOTATED, ONCOGENIC, MUTATION_EFFECT, one LEVEL column per level, HIGHEST_LEVEL and germline fields; the -d option adds descriptions (GitHub README, read 8 November 2026).
Cancer gene list, downloads and licensing
Access to OncoKB data beyond the public view is governed by account and license terms set out on the OncoKB Data Access page. MSK reports that since December 2019 doctors at other hospitals can license OncoKB for their patients, and that “scientists who use the database for academic lab research can do so for free.” Check the current Data Access terms before redistributing any downloaded content.
Citing OncoKB
The annotator documentation points to the 2017 paper (DOI 10.1200/PO.17.00011) as the reference for the knowledge base. Confirm any additional citation wording OncoKB requests when you register for access.
Three access routes compared
| Route | What it does | Needs a token | Source |
|---|---|---|---|
| Website | Look up genes, variants and levels interactively | Not applicable (see Data Access for account and license terms) | OncoKB; MSK release |
| REST API | Programmatic queries; public, demo and licensed data tiers | Yes, bearer token from Account Settings | OncoKB API page |
| Annotator scripts | Adds OncoKB columns to MAF, CNA, fusion and structural variant files | Yes, passed with -b | oncokb-annotator README |
Where it matters for labs and research offices
Teams that annotate sequencing results with OncoKB are relying on three things that change over time: the knowledge base content, the annotator version and the access tier of the token. The annotator README, for example, records that version 4.1 renamed a column to SOMATIC_ONCOGENIC_MUTATIONS, so an output file from one version is not always column-compatible with another. Editorial suggestion for a reproducible record, drawing on those facts:
- Record the annotator release or commit you ran.
- Record the date of the run, so the annotations can be tied to the data you accessed.
- Record whether the token reached public, demo or licensed data.
- Cite the 2017 paper and note the license terms under which you accessed the data.
These practices follow the general principles of computational reproducibility and the FORCE11 software citation principles. For public cohorts that are commonly annotated, see The Cancer Genome Atlas and the Genomic Data Commons. A related curated knowledge resource in pharmacogenomics is PharmGKB (ClinPGx), and the FDA Biomarker Qualification Program is a separate FDA pathway from the recognition OncoKB received.
Common misunderstandings
- “FDA approved OncoKB.” The FDA granted partial recognition of the variant classification process, not approval of the drug list on the website.
- “OncoKB is fully free.” MSK states academic lab research use is free; clinical use at other hospitals is licensed, and API token tiers control which data you see.
- “Level 3 or 4 means a drug works.” MSK describes these as evidence still under study that may suggest clinical-trial candidacy.
FAQ
What is OncoKB?
A precision oncology knowledge base from MSK that classifies cancer gene variants and assigns tumor-type-specific evidence levels.
What is the OncoKB Annotator?
A set of Python scripts that add OncoKB annotation to variants in MAF and related files, using an API token.
How do I get an OncoKB API token?
Create an account; the token appears in Account Settings once the account is approved.
What are the OncoKB levels?
Levels 1 and 2 relate to biomarkers for FDA-approved drugs; levels 3 and 4 describe evidence still being studied. See the levels section above.
Sources
- Memorial Sloan Kettering Cancer Center, “Milestone in precision oncology: FDA gives green light to MSK’s genetic database,” 4 November 2021: mskcc.org (read 8 November 2026).
- OncoKB API documentation: api.oncokb.org/oncokb-website/api (read 8 November 2026).
- OncoKB Annotator README: github.com/oncokb/oncokb-annotator (read 8 November 2026).
- Chakravarty D, et al. OncoKB: A Precision Oncology Knowledge Base. JCO Precis Oncol, 2017. doi.org/10.1200/PO.17.00011.
