Technical
How can I get access to the OncoKB API?
In order to get access to the OncoKB API, you first need to register for an account on the API/License Page. After your account is approved, you can find your token for programmatic access to the API in your Account Settings.
Will my API token expire?
Your OncoKB API token will expire after 6 months. Before it expires, we will send an email to your registered email address to verify that it is still valid. Following verification, the token will be renewed automatically.
How can I use the OncoKB API programmatically to annotate variants?
Please refer to our API documentation (https://api.oncokb.org/).
How can I access the OncoKB API with a programming language?
We recommend using Swagger Codegen to generate a client of your programming language to access the OncoKB API.
I am not familiar with APIs. What is the difference between POST and GET?
There are official definitions of GET/POST online that you can review. One example can be found here.
In OncoKB, we use POST for batch queries. For instance, you could use one GET to annotate one variant, and POST to annotate all variants in one sample (instead of sending multiple GET requests).
How can I annotate a MAF (Mutation Annotation File)?
You can annotate your MAF file by using OncoKB Annotator.
Is it necessary to know Python to use the OncoKB Annotator?
You do not necessarily need to understand Python to use the OncoKB Annotator, however, it is helpful to understand how to run the shell script.
How can I annotate a VCF (Variant Call Format)?
We recommend processing your VCF files by vcf2maf with MSK override isoforms before using the tool.
Some of the evidence retrieved from the API is not found on the OncoKB website. Should the API and website have the same information?
In general, the OncoKB API and website should contain the same data. If you notice any discrepancies, please contact us at contact@oncokb.org. One exception is the use of umbrella terms that annotate variants through logic embedded in the API. This may result in the annotation of a variant that may not be listed on the gene page of our website under “annotated alterations” (see next question regarding annotated alterations that return “Variant_in_OncoKB=false”).
The OncoKB-Annotator returned a biologic and oncogenic effect for a specific variant, but also returned “Variant_in_OncoKB=false". The variant is also not listed on your webpage. Is this a bug?
This is not a bug. We have several umbrella terms in our system that use logic to annotate variants that are not specifically curated in OncoKB. For example, we assume that truncating mutations in tumor suppressors are likely oncogenic. Therefore, if you submit a truncating mutation in TP53, for example, even if it is not specifically curated in OncoKB, it will still return a value of likely loss of function and likely oncogenic while also returning VARIANT_IN_ONCOKB=FALSE. This allows us to capture and annotate the oncogenic effect of more variants than those that are specifically curated in OncoKB.
How can a local installation of cBioPortal connect to the OncoKB API?
Your local installation of cBioPortal requires an OncoKB token. After you register for an OncoKB account and receive approval, your token will be visible in your Account Settings. Once you have the token, please follow the instructions from cBioPortal for further deployment.
Can I access data from an older version of OncoKB?
Currently, the only archival data to which we support global access are older versions of the Cancer Gene List and the Curated Gene List. The instructions for accessing older versions of these lists can be found HERE. We provide access to previous versions of OncoKB on a limited, case-by-case basis. To access, please reach out to us at contact@oncokb.org.
What are the URL patterns of OncoKB website?
Gene/Alteration page
The URL is constructed as /gene/{hugo symbol}/{alteration}/{cancer type|OncoTree code}. You need to specify at least hugo symbol in the URL.
For instance, the following formats are allowed:
The cancer type comes from OncoTree. Both name and OncoTree code are supported in the URL.
Alteration page based on HGVS
The URL is constructed as /hgvsg/{hgvsg variant}?refGenome={GRCh37|GRCh38}
For hgvsg variant format, please follow https://varnomen.hgvs.org/recommendations/DNA/
Here are examples for BRAF V600E:
GRCh37: https://www.oncokb.org/hgvsg/7:g.140453136A>T?refGenome=GRCh37
GRCh38: https://www.oncokb.org/hgvsg/7:g.140753336A>T?refGenome=GRCH38
If my genomic location is based on reference genome GRCh38, how do I annotate it?
OncoKB supports annotation in both GRCh37 and GRCh38. You can see the annotation right away on our public website with HGVSg. Here are the examples of BRAF V600E in GRCh37 and GRCh38:
GRCh37: https://www.oncokb.org/hgvsg/7:g.140453136A>T?refGenome=GRCh37
GRCh38: https://www.oncokb.org/hgvsg/7:g.140753336A>T?refGenome=GRCh38
You can also use our annotation endpoints to annotate your variants by specifying the reference genome.
Using HGVSg, please see https://api.oncokb.org/oncokb-website/api#annotate-mutations-by-hgvsg
Using genomic location, please see https://api.oncokb.org/oncokb-website/api#annotate-mutations-by-genomic-change
The feature is powered by Genome Nexus and reVUE.
How do I convert my protein change to your isoform (RefSeq)?
OncoKB maintains a list of genes, including the isoform ID and RefSeq ID, for both GRCh37 and GRCh38. You can download the list at https://www.oncokb.org/cancerGenes.
I am located in Europe. Can I use OncoKB while still adhering to the EU’s General Data Protection Regulation (GDPR)?
Yes. We have many users in Europe, both academic and commercial, who use OncoKB through https://eucentral.oncokb.org which is located in Frankfurt, Germany. If you have questions about this, please don’t hesitate to reach out to us at contact@oncokb.org.
Last updated