# Introduction

Welcome to the documentation for OncoKB™.

## Background

OncoKB™ is a Precision Oncology Knowledgebase that contains information about the biological effects and treatment implications of specific cancer genes and their somatic alterations. OncoKB™ is developed and maintained by the Knowledge Systems group in the Marie Josée and Henry R. Kravis Center for Molecular Oncology at the Memorial Sloan Kettering Cancer Center (MSK).

## OncoKB™ Processes

The schematic shows a summary of the data sources, knowledgebase architecture and processes that compose the OncoKB™ workflow. As is shown, OncoKB™ curators will keep monitoring data changes from multiple data sources and edit changed content via OncoKB™ curation platform. Next step, the Lead Scientists will review modified content to approve/reject it. Once it gets approval, it will be send to database and updated to OncoKB™ Access in realtime.

![Summary of OncoKB™ processes](https://623726595-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M2noZm_5yXK2lyMYR1S%2F-M33gkY4MWd0H4n7iRN5%2F-M33nTapdFebVai4K393%2Fprocess.png?alt=media\&token=e8bf1a7a-6a2e-4f67-a5d1-963433520fa6)


# Architecture

## Overview

OncoKB™ website consists of following components:

* Frontend built with React, Mobx and Bootstrap
* User/Permission management backend written in Java with Spring Boot
* Annotation service(core) backend written in Java
* MySQL databases

The frontend is a single page app built with React, Mobx and Bootstrap. The data gets pulled from the backend REST APIs. The frontend is by default included with the backend so no extra setup is required.

The backends are written in Java and connects to MySQL databases to serve a REST API generated by swagger (<https://www.oncokb.org/swagger-ui/index.html>).

![](https://623726595-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M2noZm_5yXK2lyMYR1S%2F-M37e_p6waV4IS05GeqW%2F-M380AJQbxFxDuFBU8-F%2FOncoKB%20Architecture.png?alt=media\&token=92c8ae76-2c5e-4c17-95a7-2e34e0f3c0f1)


# API Info

### Overview

OncoKB™ data can be accessed through the OncoKB™ REST API. The full interactive API reference is available on the [Swagger page](https://www.oncokb.org/swagger-ui/index.html).

### Authentication

Send your OncoKB™ API token in the `Authorization` request header:

```
Authorization: Bearer [your token]
```

Your token is available in [Account Settings](https://www.oncokb.org/account/settings) after your account is approved. If you do not see a token, then follow instructions on the page to request API access.

See the [Data Access page](https://www.oncokb.org/dataAccess) for account and license information.

{% hint style="warning" %}
An API token identifies your OncoKB account and determines which licensed data your requests can access. Keep the token private, do not include it in public code repositories or share it with others.
{% endhint %}

### Instances

| Instance                        | Authentication | Use case                                                              |
| ------------------------------- | -------------- | --------------------------------------------------------------------- |
| `https://www.oncokb.org`        | Required       | Production use and the complete OncoKB™ data                          |
| `https://public.api.oncokb.org` | Not required   | Public API access across all genes, excluding therapeutic data        |
| `https://demo.oncokb.org`       | Not required   | Trial and integration testing with full data for BRAF, TP53, and ROS1 |

All instances use the latest OncoKB™ data version. See [OncoKB News](https://www.oncokb.org/news) for data release notes.

### Endpoint Quick Reference

{% hint style="success" icon="lightbulb" %}
Annotation endpoints support both `GET` and `POST`. Use `GET` for one-off queries and `POST` for batch annotation.
{% endhint %}

#### Somatic Annotation

| Method         | Endpoint                                     | Primary input                                                                                                   |
| -------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `GET` / `POST` | `/api/v1/annotate/mutations/byProteinChange` | Gene and protein change                                                                                         |
| `GET` / `POST` | `/api/v1/annotate/mutations/byGenomicChange` | TCGA MAF-style genomic location                                                                                 |
| `GET` / `POST` | `/api/v1/annotate/mutations/byHGVSg`         | HGVS genomic expression                                                                                         |
| `GET` / `POST` | `/api/v1/annotate/copyNumberAlterations`     | Gene and copy number alteration type                                                                            |
| `GET` / `POST` | `/api/v1/annotate/structuralVariants`        | Use this endpoint for fusion annotation when you have a gene pair, or for other structural variant annotations. |

#### Germline Annotation

| Method         | Endpoint                                              | Primary input                   |
| -------------- | ----------------------------------------------------- | ------------------------------- |
| `GET` / `POST` | `/api/v1/annotate/germline/mutations/byGenomicChange` | TCGA MAF-style genomic location |
| `GET` / `POST` | `/api/v1/annotate/germline/mutations/byHGVSg`         | HGVS genomic expression         |
| `GET` / `POST` | `/api/v1/annotate/germline/mutations/byHGVSc`         | HGVS coding DNA expression      |

### Common Parameters

The same parameter names are used across many annotation endpoints. Endpoint-specific tables below this section show which parameters are accepted and whether they are required for that endpoint.

| Parameter         | Description                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `referenceGenome` | Reference genome build. Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                                                                                               |
| `tumorType`       | See [OncoTree](https://oncotree.mskcc.org/) for available tumor types. The field supports OncoTree code, OncoTree name (subtype), and OncoTree main type. Example values include `MEL` or `Melanoma` |
| `hugoSymbol`      | HUGO gene symbol. When an endpoint accepts gene identifiers, provide either `hugoSymbol` or `entrezGeneId`. If both are provided, then `entrezGeneId` takes priority. Example: `BRAF`.               |
| `entrezGeneId`    | Entrez gene ID. Use this instead of `hugoSymbol` when you prefer a numeric gene identifier. Example: `673` for BRAF.                                                                                 |
| `consequence`     | Sequence ontology [consequence](http://useast.ensembl.org/info/genome/variation/prediction/predicted_data.html). Example: `missense_variant`                                                         |
| `genomicLocation` | TCGA MAF-style genomic location in `chromosome,start,end,ref,var` format. Example: `7,140453136,140453136,A,T`.                                                                                      |
| `hgvsg`           | [HGVS](https://hgvs-nomenclature.org/stable/) genomic expression. Example: `7:g.140453136A>T`.                                                                                                       |
| `hgvsc`           | [HGVS](https://hgvs-nomenclature.org/stable/) coding DNA expression. Example: `EGFR:c.2369C>T`.                                                                                                      |

### Somatic Annotation Endpoints

{% hint style="warning" %}
For germline variants, use the `/api/v1/annotate/germline/...` endpoints instead of the somatic `/api/v1/annotate/...` endpoints. API users should determine whether each queried variant is somatic or germline and choose the corresponding endpoint. If the origin of a variant is unknown, users can call both the somatic and germline endpoints.

The existing annotation endpoints do not include `/somatic` in the URL because OncoKB was a somatic knowledge base until the recent release of germline, and we preserved the original URL structure to avoid breaking existing workflows.
{% endhint %}

#### Annotate Mutations by Protein Change

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

Use this endpoint when you have a gene and protein-level alteration, including atypical alterations.

| Parameter         | Required    | Type    | Description                                                                                                                                   |
| ----------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `hugoSymbol`      | Conditional | string  | Required if `entrezGeneId` is not provided. Example: `BRAF`.                                                                                  |
| `entrezGeneId`    | Conditional | integer | Required if `hugoSymbol` is not provided. Example: `673`.                                                                                     |
| `alteration`      | No          | string  | Protein change, supported atypical alteration, or umbrella term. Example: `V600E`, `Truncating Mutations`, `TMB-H`                            |
| `referenceGenome` | No          | string  | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                                                                |
| `consequence`     | No          | string  | Sequence ontology [consequence](http://useast.ensembl.org/info/genome/variation/prediction/predicted_data.html). Example: `missense_variant`. |
| `proteinStart`    | No          | integer | Protein start position. Example: `600`.                                                                                                       |
| `proteinEnd`      | No          | integer | Protein end position. Example: `600`.                                                                                                         |
| `tumorType`       | No          | string  | See [Common Parameters](#common-parameters). Example: `Melanoma`.                                                                             |

```bash
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 token]"
```

Demo:

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

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/mutations/byProteinChange" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "gene": { "hugoSymbol": "BRAF" },
      "alteration": "V600E",
      "tumorType": "Melanoma"
    }
  ]'
```

**Atypical Alterations**

Use the somatic protein change endpoint for atypical alterations. Examples of atypical alterations, but not limited to:

| Gene         | Queryable Alteration Value                                                                                                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AR`         | [v567es](https://www.oncokb.org/gene/AR/somatic/V567ES)                                                                                                                                              |
| `AR`         | [V7](https://www.oncokb.org/gene/AR/somatic/V7) (previously annotated as `AR-V7`)                                                                                                                    |
| `EGFR`       | [vII](https://www.oncokb.org/gene/EGFR/somatic/vII), [vIII](https://www.oncokb.org/gene/EGFR/somatic/vIII), [vV](https://www.oncokb.org/gene/EGFR/somatic/vV) (variant isoforms)                     |
| `EGFR`       | [C-terminal domain](https://www.oncokb.org/gene/EGFR/somatic/C-terminal%20domain) or [CTD](https://www.oncokb.org/gene/EGFR/somatic/CTD)                                                             |
| `FLT3`       | [Internal Tandem Duplication](https://www.oncokb.org/gene/FLT3/somatic/Internal%20Tandem%20Duplication) or [ITD](https://www.oncokb.org/gene/FLT3/somatic/ITD)                                       |
| `BCOR`       | [Internal Tandem Duplication](https://www.oncokb.org/gene/BCOR/somatic/Internal%20Tandem%20Duplication) or [ITD](https://www.oncokb.org/gene/BCOR/somatic/ITD)                                       |
| `UBTF`       | [Internal Tandem Duplication](https://www.oncokb.org/gene/UBTF/somatic/Internal%20Tandem%20Duplication) or [ITD](https://www.oncokb.org/gene/UBTF/somatic/ITD)                                       |
| `EGFR`       | [Kinase Domain Duplication](https://www.oncokb.org/gene/EGFR/somatic/Kinase%20Domain%20Duplication) or [KDD](https://www.oncokb.org/gene/EGFR/somatic/KDD)                                           |
| `BRAF`       | [Kinase Domain Duplication](https://www.oncokb.org/gene/BRAF/somatic/Kinase%20Domain%20Duplication) or [KDD](https://www.oncokb.org/gene/BRAF/somatic/KDD)                                           |
| `FGFR1`      | [Kinase Domain Duplication](https://www.oncokb.org/gene/FGFR1/somatic/Kinase%20Domain%20Duplication) or [KDD](https://www.oncokb.org/gene/FGFR1/somatic/KDD)                                         |
| `MET`        | [Kinase Domain Duplication](https://www.oncokb.org/gene/MET/somatic/Kinase%20Domain%20Duplication) or [KDD](https://www.oncokb.org/gene/MET/somatic/KDD)                                             |
| Not required | [Tumor Mutational Burden-High](https://www.oncokb.org/gene/Other%20Biomarkers/somatic/Tumor%20Mutational%20Burden-High) or [TMB-H](https://www.oncokb.org/gene/Other%20Biomarkers/somatic/TMB-H)     |
| Not required | [Microsatellite Instability-High](https://www.oncokb.org/gene/Other%20Biomarkers/somatic/Microsatellite%20Instability-High) or [MSI-H](https://www.oncokb.org/gene/Other%20Biomarkers/somatic/MSI-H) |

Examples:

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

```bash
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 Mutations by Genomic Change

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

Use this endpoint when you have chromosome, start, end, reference allele, and variant allele.

| Parameter         | Required | Type   | Description                                                                                                     |
| ----------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `genomicLocation` | Yes      | string | TCGA MAF-style genomic location in `chromosome,start,end,ref,var` format. Example: `7,140453136,140453136,A,T`. |
| `referenceGenome` | No       | string | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                                  |
| `tumorType`       | No       | string | See [Common Parameters](#common-parameters).                                                                    |

```bash
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 token]"
```

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/mutations/byGenomicChange" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "genomicLocation": "7,140453136,140453136,A,T",
      "tumorType": "Melanoma"
    }
  ]'
```

#### Annotate Mutations by HGVSg

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

Use this endpoint when you have an HGVS genomic expression.

| Parameter         | Required | Type   | Description                                                                                    |
| ----------------- | -------- | ------ | ---------------------------------------------------------------------------------------------- |
| `hgvsg`           | Yes      | string | [HGVS](https://hgvs-nomenclature.org/stable/) genomic expression. Example: `7:g.140453136A>T`. |
| `referenceGenome` | No       | string | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                 |
| `tumorType`       | No       | string | See [Common Parameters](#common-parameters).                                                   |

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

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/mutations/byHGVSg" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "hgvsg": "7:g.140453136A>T",
      "tumorType": "Melanoma"
    }
  ]'
```

#### Annotate Copy Number Alterations

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

| Parameter                | Required    | Type    | Description                                                    |
| ------------------------ | ----------- | ------- | -------------------------------------------------------------- |
| `hugoSymbol`             | Conditional | string  | Required if `entrezGeneId` is not provided. Example: `BRAF`.   |
| `entrezGeneId`           | Conditional | integer | Required if `hugoSymbol` is not provided. Example: `673`.      |
| `copyNameAlterationType` | Yes         | string  | One of `AMPLIFICATION`, `DELETION`, `GAIN`, `LOSS`.            |
| `referenceGenome`        | No          | string  | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`. |
| `tumorType`              | No          | string  | See [Common Parameters](#common-parameters).                   |

```bash
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 token]"
```

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/copyNumberAlterations" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "gene": { "hugoSymbol": "BRAF" },
      "copyNameAlterationType": "AMPLIFICATION",
      "tumorType": "Melanoma"
    }
  ]'
```

#### Annotate Structural Variants

`GET https://www.oncokb.org/api/v1/annotate/structuralVariants`

Use this endpoint for fusion annotation when you have a gene pair, or for other structural variant annotations.

| Parameter               | Required | Type    | Description                                                                                                                                                                   |
| ----------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hugoSymbolA`           | No       | string  | First gene symbol                                                                                                                                                             |
| `entrezGeneIdA`         | No       | integer | First Entrez gene ID. Not required when `hugoSymbolA` is passed                                                                                                               |
| `hugoSymbolB`           | No       | string  | <p>Second gene symbol.<br>For intragenic events, this field can be omitted or set to the same as <code>hugoSymbolA</code>.<br>For fusions, specify the gene partner here.</p> |
| `entrezGeneIdB`         | No       | integer | Second Entrez gene ID. Not required when `hugoSymbolB` is passed                                                                                                              |
| `structuralVariantType` | Yes      | string  | One of `DELETION`, `TRANSLOCATION`, `DUPLICATION`, `INSERTION`, `INVERSION`, `FUSION`, `UNKNOWN`.                                                                             |
| `isFunctionalFusion`    | Yes      | boolean | Whether the event is a functional fusion. Set to true when annotating fusions.                                                                                                |
| `referenceGenome`       | No       | string  | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                                                                                                |
| `tumorType`             | No       | string  | See [Common Parameters](#common-parameters).                                                                                                                                  |

```bash
curl -X GET "https://www.oncokb.org/api/v1/annotate/structuralVariants?hugoSymbolA=CD74&hugoSymbolB=ROS1&structuralVariantType=FUSION&isFunctionalFusion=true&tumorType=Lung%20Adenocarcinoma" \
  -H "accept: application/json" \
  -H "Authorization: Bearer [your token]"
```

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/structuralVariants" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "geneA": { "hugoSymbol": "CD74" },
      "geneB": { "hugoSymbol": "ROS1" },
      "structuralVariantType": "FUSION",
      "functionalFusion": true,
      "tumorType": "Lung Adenocarcinoma"
    }
  ]'
```

### Germline Annotation Endpoints

#### Annotate Germline Mutations by Genomic Change

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

| Parameter         | Required | Type   | Description                                                                                                     |
| ----------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `genomicLocation` | Yes      | string | TCGA MAF-style genomic location in `chromosome,start,end,ref,var` format. Example: `7,140453136,140453136,A,T`. |
| `referenceGenome` | No       | string | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                                  |
| `tumorType`       | No       | string | See [Common Parameters](#common-parameters).                                                                    |

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

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/germline/mutations/byGenomicChange" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "genomicLocation": "7,140453136,140453136,A,T",
      "tumorType": "Melanoma"
    }
  ]'
```

#### Annotate Germline Mutations by HGVSg

`GET https://www.oncokb.org/api/v1/annotate/germline/mutations/byHGVSg`

| Parameter         | Required | Type   | Description                                                                                    |
| ----------------- | -------- | ------ | ---------------------------------------------------------------------------------------------- |
| `hgvsg`           | Yes      | string | [HGVS](https://hgvs-nomenclature.org/stable/) genomic expression. Example: `7:g.140453136A>T`. |
| `referenceGenome` | No       | string | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                 |
| `tumorType`       | No       | string | See [Common Parameters](#common-parameters).                                                   |

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

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/germline/mutations/byHGVSg" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "hgvsg": "7:g.140453136A>T",
      "tumorType": "Melanoma"
    }
  ]'
```

#### Annotate Germline Mutations by HGVSc

`GET https://www.oncokb.org/api/v1/annotate/germline/mutations/byHGVSc`

| Parameter         | Required | Type   | Description                                                                                     |
| ----------------- | -------- | ------ | ----------------------------------------------------------------------------------------------- |
| `hgvsc`           | Yes      | string | [HGVS](https://hgvs-nomenclature.org/stable/) coding DNA expression. Example: `EGFR:c.2369C>T`. |
| `referenceGenome` | No       | string | Supported values are `GRCh37` and `GRCh38`. Default: `GRCh37`.                                  |
| `tumorType`       | No       | string | See [Common Parameters](#common-parameters).                                                    |

```bash
curl -X GET "https://www.oncokb.org/api/v1/annotate/germline/mutations/byHGVSc?hgvsc=EGFR%3Ac.2369C%3ET" \
  -H "accept: application/json" \
  -H "Authorization: Bearer [your token]"
```

Batch request:

```bash
curl -X POST "https://www.oncokb.org/api/v1/annotate/germline/mutations/byHGVSc" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [your token]" \
  -d '[
    {
      "referenceGenome": "GRCh37",
      "hgvsc": "EGFR%3Ac.2369C%3ET",
    }
  ]'
```

#### Annotate Germline Mutations by HGVSp (Protein Change)

{% hint style="danger" %}
We currently do not support germline annotation by protein change because a single protein change can correspond to multiple cDNA or genomic changes, and those differences may affect interpretation. We are actively working through how to support this with clear disambiguation.
{% endhint %}

### Common Use Cases

| Use case                                | Example request                                                                                                                                                                     |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missense mutation in an oncogene        | `https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF&alteration=V600E&tumorType=Melanoma`                                                             |
| Missense mutation in a tumor suppressor | `https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=TP53&alteration=R273C&tumorType=Colon%20Adenocarcinoma`                                               |
| In-frame deletion                       | `https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF&alteration=N486_P490del&tumorType=Histiocytosis`                                                 |
| Fusion                                  | `https://demo.oncokb.org/api/v1/annotate/structuralVariants?hugoSymbolA=CD74&hugoSymbolB=ROS1&structuralVariantType=FUSION&isFunctionalFusion=true&tumorType=Lung%20Adenocarcinoma` |

### Important Notes

* For CDKN2A isoforms, use the following values for the `hugoSymbol` parameter:

  ```
  CDKN2A (p14)  → queries p14
  CDKN2A        → queries p16
  ```

  When no isoform suffix is provided, `CDKN2A` defaults to p16.

### Notes and Changelog

* The `evidenceType` parameter is deprecated and not recommended for use. It was marked deprecated as of OncoKB software version `v3.24.0` (December 19, 2024) and may be removed in a future release.

### Annotating MAF/VCF

For MAF files, use the [OncoKB Annotator](https://github.com/oncokb/oncokb-annotator). The OncoKB Annotator is a Python command-line script that wraps the OncoKB REST API and streamlines annotation of MAF files. It handles reading input variants, calling the appropriate OncoKB annotation endpoints, and writing annotated MAF output.

Since OncoKB Annotator only supports MAF files, one option is to use [genome-nexus/vcf2maf-lite](https://github.com/genome-nexus/vcf2maf-lite).


# API Benchmark

## Introduction

The OncoKB Development team has conducted API performance tests to identify optimization opportunities and collect key metrics for evaluating overall API capabilities. You’ll find key performance indicators such as response times, throughput, and resource utilization across different endpoints.

## Annotate Mutation by HGVS

### 10/24/2024

This test aims to determine the performance of the `annotate/mutations/byHGVSg` endpoint given that the variants have been annotated and cached by Genome Nexus.

### Datasets

We have chosen the following studies for benchmarking:

1. **Whole Exome Sequencing Dataset:** [UCSC Xena: Simple Somatic Mutation (SNVs and indels) - Consensus Coding Mutations](https://xenabrowser.net/datapages/?dataset=October_2016_all_patients_2778.snv_mnv_indel.maf.coding.xena\&host=https%3A%2F%2Fpcawg.xenahubs.net\&removeHub=https%3A%2F%2Fxena.treehouse.gi.ucsc.edu%3A443)
   * ***441,309*** variants across ***2,756*** samples
2. **Whole Genome Sequencing Dataset:** [UCSC Xena: Simple Somatic Mutation (SNVs and indels) - Whole Genome Mutations (Non-US Specimens)](https://xenabrowser.net/datapages/?dataset=October_2016_all_patients_2778.snv_mnv_indel.maf.xena.nonUS\&host=https%3A%2F%2Fpcawg.xenahubs.net\&removeHub=https%3A%2F%2Fxena.treehouse.gi.ucsc.edu%3A443)
   * ***23,159,591*** variants across ***1,950*** samples

### Services Setup

These tests will be conducted by replicating the production setup. All configurations can be found [here](https://github.com/knowledgesystems/knowledgesystems-k8s-deployment/tree/master/oncokb/oncokb-msk/dev/api-load-testing).

### Test Setup

We will be using [Locust.io](https://www.locust.io) to write our performance tests.

As a prerequisite, all variants from WES and WGS datasets have been annotated (and cached in Genome Nexus) prior to benchmarking OncoKB HGVSg endpoint.

<details>

<summary>Running Tests</summary>

{% code title="single\_thread\_test.py" fullWidth="false" %}

```python
from locust import HttpUser, task, events
import time

# Data to annotate for test
variants_list = []
with open("wgs.txt", "r") as data_file:
    variants_list = [{"hgvsg": row.strip()} for row in data_file
variant_batches = list(chunk_variants(variants_list))

# Global variables to track total time and batches
start_time = None
total_batches = len(variant_batches)
completed_batches = 0

# Batch the WES/WGS dataset into chunks of 100 variants
def chunk_variants(variants, chunk_size=100):
    for i in range(0, len(variants), chunk_size):
        yield variants[i:i + chunk_size]
        
# Locust test on start listener
@events.test_start.add_listener
def on_test_start(environment, **kwargs):
    global start_time
    start_time = time.time()
    
# When test stops, then print out how long it took
@events.test_stop.add_listener
def on_test_stop(environment, **kwargs):
    end_time = time.time()
    total_time = end_time - start_time
    print(f"Total time to process {total_batches * 100} variants: {total_time:.2f} seconds")


class OncoKBUser(HttpUser):
    @task
    def sendRequest(self):
        global completed_batches
        if completed_batches < total_batches:
            batch = variant_batches[completed_batches]
            # Send POST request with Authorization header
            response = self.client.post(
                "/api/v1/annotate/mutations/byHGVSg", 
                headers={"Content-Type": "application/json","Authorization": "Bearer <token>"},
                data=json.dumps(batch), timeout=600000
            )
            
            
            # Track batch completion
            completed_batches += 1
            
            # Check response time for each request
            print(f"Request {completed_batches}/{total_batches} completed in {response.elapsed.total_seconds()} seconds")
        else:
            self.environment.runner.quit()
```

{% endcode %}

{% code title="multi\_thread\_test.py" %}

```python
from locust import HttpUser, task, events
import time

# Data to annotate for test
variants_list = []
with open("wgs.txt", "r") as data_file:
    variants_list = [{"hgvsg": row.strip()} for row in data_file
variant_batches = list(chunk_variants(variants_list))

# Global variables to track total time and batches
start_time = None
total_batches = len(variant_batches)
completed_batches = 0
lock = Lock()
active_users = 0

# Batch the WES/WGS dataset into chunks of 100 variants
def chunk_variants(variants, chunk_size=100):
    for i in range(0, len(variants), chunk_size):
        yield variants[i:i + chunk_size]
        
# Locust test on start listener
@events.test_start.add_listener
def on_test_start(environment, **kwargs):
    global start_time
    global active_users
    # Initialize active user count with the number of users in the test
    active_users = environment.runner.user_count
    start_time = time.time()
    
# When test stops, then print out how long it took
@events.test_stop.add_listener
def on_test_stop(environment, **kwargs):
    end_time = time.time()
    total_time = end_time - start_time
    print(f"Total time to process {total_batches * 100} variants: {total_time:.2f} seconds")


class OncoKBUser(HttpUser):
    def get_next_batch(self):
        global completed_batches
        with lock:
            print(completed_batches)
            if completed_batches < total_batches:
                batch = variant_batches[completed_batches]
                completed_batches += 1
                print(batch[0])
                return batch
            else:
                return None  # No more batches available

    @task
    def send5Threads(self):
        batch = self.get_next_batch()
        if batch is None:
            global active_users
            with lock:
                active_users -= 1  # Mark the user as finished

                # If all users are done processing, stop the test
                if active_users < 0:
                    print("All users finished processing. Stopping test.")
                    self.environment.runner.quit()  # Stop the entire test
                    signal.raise_signal(signal.SIGTERM)
            return
    
        response = self.client.post(
            "/api/v1/annotate/mutations/byHGVSg", 
            headers={"Content-Type": "application/json","Authorization": "Bearer <token>"},
            data=json.dumps(batch)
        )
        
        print(f"Request {completed_batches}/{total_batches} completed in {response.elapsed.total_seconds()} seconds")

```

{% endcode %}

```
$ locust -f <file_name>.py --run-time 24h --host=https://www.oncokb.dev.aws.mskcc.org
```

</details>

### Performance Benchmark Results

#### Test 1: How long does it take to annotate each study using a single thread?

Redis caching was disabled for this test. Each thread was ran sequentially until the entire dataset was annotated.

Annotate **1** thread containing a POST request with 100 variants.

**WES Dataset:**

441,309 variants: 835 seconds or 14 minutes (***528*** variants/second)

**WGS Dataset**:

23,159,591 variants: 17,508seconds or 4hrs 52mins (***1,322*** variants/second)

***

#### Test 2: Do we gain a performance boost using 5 threads instead of 1?

Redis caching was disabled for this test.

Annotate up to ***5*** threads concurrently, each executing a POST request containing 100 variants.

**WES Dataset:**

441,309 variants: 151 seconds or 2.51minutes (***2,922*** variants/second)

**WGS Dataset:**

23,159,591 variants: 3,482seconds or 58mins (***6,652*** variants/second)

Increasing the number of threads to five boosted the throughput, allowing for a fivefold increase in the number of variants annotated per second.

***

## Genome Nexus VEP Benchark

When annotating mutations by genomic change or HGVSg, OncoKB uses [Genome Nexus](https://www.genomenexus.org/) to convert these formats to HGVSp for annotation, which leverages [Ensembl's Variant Effect Predictor (VEP)](https://useast.ensembl.org/info/docs/tools/vep/index.html). Genome Nexus recommends 2 main configuration options for using VEP:\
\
1\. [Genome Nexus VEP](https://github.com/genome-nexus/genome-nexus-vep) (Local, Recommended)\
2\. [Ensembl REST API](https://rest.ensembl.org/) (Public)\
\
Both provide a REST API wrapper around the VEP command line interface and can be leveraged depending on the user's performance, security, and convenience needs. Below you can find the results of each tool when annotating POST requests of varying sizes using the `vep/human/hgvs` endpoint:

### Genome Nexus VEP

| # Variants | Run 1  | Run 2  | Run 3  | Run 4  | Run 5  |
| ---------- | ------ | ------ | ------ | ------ | ------ |
| 1          | 772ms  | 755ms  | 748ms  | 708ms  | 723ms  |
| 5          | 1.25s  | 1.28s  | 1.14s  | 1.21s  | 1.29s  |
| 10         | 1.90s  | 1.73s  | 1.90s  | 1.93s  | 1.80s  |
| 50         | 4.21s  | 4.40s  | 4.36s  | 4.05s  | 4.05s  |
| 100        | 6.02s  | 6.71s  | 6.33s  | 6.46s  | 6.62s  |
| 1000       | 62.82s | 62.10s | 62.16s | 62.10s | 62.52s |

### Ensembl REST API

| # Variants          | Run 1  | Run 2  | Run 3  | Run 4  | Run 5  |
| ------------------- | ------ | ------ | ------ | ------ | ------ |
| 1                   | 1.79s  | 1.27s  | 1.79s  | 1.31s  | 1.82s  |
| 5                   | 4.54s  | 3.40s  | 3.81s  | 3.82s  | 3.62s  |
| 10                  | 8.01s  | 6.95s  | 7.08s  | 7.60s  | 6.75s  |
| 50                  | 39.52s | 37.79s | 41.06s | 39.93s | 38.82s |
| 100                 | 83.28s | 87.60s | 87.78s | 68.82s | 72.78s |
| 1000 (Limit is 300) | NA     | NA     | NA     | NA     | NA     |


# Variant Annotators

{% hint style="info" %}
Coming Soon: Germline support for OncoKB Annotator
{% endhint %}

## Introduction

Annotates variants in MAF with OncoKB™ annotation. Supports both python2 and python3.

* **MafAnnotator.py**: A Mutation Annotation Format (MAF) file is a tab-delimited text file that lists mutations. MAFAnnotator annotated genes from MAF file by [OncoKB™ Level of Evidences](https://www.oncokb.org/levels) rules.
* **FusionAnnotator.py**: Annotate fusions by [OncoKB™ Level of Evidences](https://www.oncokb.org/levels) rules.
* **CnaAnnotator.py**: Annotate copy number alterations by [OncoKB Level of Evidences](https://www.oncokb.org/levels) rules.
* **ClinicalDataAnnotator.py**: Annotate clinical data by [OncoKB™ Level of Evidences](https://www.oncokb.org/levels) rules.
* **OncoKBPlots.py**: Draw OncoKB™ Actionability genes graph.<br>

Please run the commands below to see usage details in terminal.

```bash
python MafAnnotator.py -h
python FusionAnnotator.py -h
python CnaAnnotator.py -h
python ClinicalDataAnnotator.py -h
python OncoKBPlots.py -h
```

{% hint style="info" %}
We recommend processing VCF files by [vcf2maf](https://github.com/mskcc/vcf2maf/) with [MSK override isoforms](https://github.com/mskcc/vcf2maf/blob/master/data/isoform_overrides_at_mskcc) before using the **MafAnnotator** here.
{% endhint %}

Please go to [OncoKB™ Annotator Github Repository](https://github.com/oncokb/oncokb-annotator) to see source code and more details.

## OncoKB™ API Token

When you run `MafAnnotator.py`, `FusionAnnotator.py` and `CnaAnnotator.py`, you need a token before accessing the OncoKB™ data via its web API. Please visit [OncoKB™ Data Access Page](https://www.oncokb.org/dataAccess) for more information about how to register an account and get an OncoKB™ API token.\
With the token listed under [OncoKB™ Account Settings Page](https://www.oncokb.org/account/settings), you could use it in the following format.

```bash
python ${FILE_NAME.py} -i ${INPUT_FILE} -o ${OUTPUT_FILE} -b ${ONCOKB_API_TOKEN}
```

## Python Examples

### MAF Annotator

When you type `python MafAnnotator.py -h` in terminal, you can see all Python command parameters as below. `-i <input MAF file>`, `-o <output MAF file>` and`-b oncokb_api_bear_token` are required.

```bash
MafAnnotator.py -i <input MAF file> -o <output MAF file> [-p previous results] [-c <input clinical file>] [-s sample list filter] [-t <default tumor type>] [-u oncokb-base-url] [-b oncokb_api_bear_token] [-a]
Essential MAF columns (case insensitive):
    HUGO_SYMBOL: Hugo gene symbol
    VARIANT_CLASSIFICATION: Translational effect of variant allele
    TUMOR_SAMPLE_BARCODE: sample ID
    AMINO_ACID_CHANGE: amino acid change
    PROTEIN_START: protein start
    PROTEIN_END: protein end
    PROTEIN_POSITION: can be used instead of PROTEIN_START and PROTEIN_END (in the output of vcf2map)
Essential clinical columns:
    SAMPLE_ID: sample ID
    ONCOTREE_CODE: tumor type code from oncotree (oncotree.mskcc.org)
Cancer type will be assigned based on the following priority:
    1) ONCOTREE_CODE in clinical data file
    2) ONCOTREE_CODE exist in MAF
    3) default tumor type (-t)
Default OncoKB™ base url is http://oncokb.org.
Use -a to annotate mutational hotspots
```

### Fusion Annotator

When you type python `FusionAnnotator.py -h` in terminal, you can see all Python command parameters as below. The required parameters is the same with MAF Annotator.

```bash
FusionAnnotator.py -i <input Fusion file> -o <output Fusion file> [-p previous results] [-c <input clinical file>] [-s sample list filter] [-t <default tumor type>] [-u oncokb-base-url] [-b oncokb_api_bear_token]
  Essential Fusion columns (case insensitive):
    HUGO_SYMBOL: Hugo gene symbol
    VARIANT_CLASSIFICATION: Translational effect of variant allele
    TUMOR_SAMPLE_BARCODE: sample ID
    FUSION: amino acid change, e.g. "TMPRSS2-ERG fusion"
  Essential clinical columns:
    SAMPLE_ID: sample ID
    ONCOTREE_CODE: tumor type code from oncotree (oncotree.mskcc.org)
  Cancer type will be assigned based on the following priority:
     1) ONCOTREE_CODE in clinical data file
     2) ONCOTREE_CODE exist in Fusion
     3) default tumor type (-t)
  Default OncoKB™ base url is http://oncokb.org
```

### CNA Annotator

When you type python `CnaAnnotator.py -h` in terminal, you can see all Python command parameters as below. The required parameters is the same with MAF Annotator.

```bash
CnaAnnotator.py -i <input CNA file> -o <output CNA file> [-p previous results] [-c <input clinical file>] [-s sample list filter] [-t <default tumor type>] [-u oncokb-base-url] [-b oncokb_api_bear_token]
  Input CNA file should follow the GISTIC output (https://cbioportal.readthedocs.io/en/latest/File-Formats.html#discrete-copy-number-data)
  Essential clinical columns:
    SAMPLE_ID: sample ID
  Cancer type will be assigned based on the following priority:
     1) ONCOTREE_CODE in clinical data file
     2) ONCOTREE_CODE exist in MAF
     3) default tumor type (-t)
  Default OncoKB™ base url is http://oncokb.org
```

### Clinical Data Annotator

When you type python `ClinicalDataAnnotator.py -h` in terminal, you can see all Python command parameters as below. `-i <input clinical file>`, `-o <output clinical file>` and`-a <annotated alteration files, separate by ,>` are required.

```bash
ClinicalDataAnnotator.py -i <input clinical file> -o <output clinical file> -a <annotated alteration files, separate by ,> [-s sample list filter]
  Essential clinical columns:
    SAMPLE_ID: sample ID
```

### OncoKB Plots

When you type `python OncoKBPlots.py -h` in terminal, you can see all Python command parameters as below. `-i <input clinical file>` and `-o <output clinical file>` are required.

```bash
OncoKBPlots.py -i <annotated clinical file> -o <output PDF file> [-c <categorization column, e.g. CANCER_TYPE>] [-s sample list filter] [-n threshold of # samples in a category] [-l comma separated levels to include]
  Essential clinical columns:
    SAMPLE_ID: sample ID
    HIGHEST_LEVEL: Highest OncoKB levels
  Supported levels (-l): 
    LEVEL_1,LEVEL_2,LEVEL_3A,LEVEL_3B,LEVEL_4,ONCOGENIC,VUS
```