# API Info

## Introduction

The OncoKB™ data can be accessed through a [REST API (Swagger Page)](https://www.oncokb.org/swagger-ui/index.html). The API is defined and organized using swagger annotation. MAF file annotation is also possible by using [OncoKB™ Annotator](https://github.com/oncokb/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](https://www.oncokb.org/dataAccess) 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](https://www.oncokb.org/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.&#x20;

### <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](https://www.oncokb.org/swagger-ui/index.html). We only list GET methods here. They all have corresponding POST method available. Please see the [Swagger page](https://www.oncokb.org/swagger-ui/index.html) for more details.

## Annotate Mutations by Protein Change

<mark style="color:blue;">`GET`</mark> `https://www.oncokb.org/api/v1/annotate/mutations/byProteinChange`                      &#x20;

#### 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 |

{% tabs %}
{% tab title="200 Annotate mutations by protein change successfully." %}

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

{% endtab %}
{% endtabs %}

### Curl Example

#### [www.oncokb](http://www.oncokb)

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

#### demo.oncokb

```bash
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](https://demo.oncokb.org/api/v1/annotate/mutations/byProteinChange?hugoSymbol=BRAF\&alteration=V600E\&tumorType=Melanoma)

#### 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&#x20;

* 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]'
```

## &#x20;Annotate Copy Number Alterations

<mark style="color:blue;">`GET`</mark> `https://www.oncokb.org/api/v1/annotate/copyNumberAlterations`                              &#x20;

#### 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. |

{% tabs %}
{% tab title="200 Annotate copy number alterations successfully." %}

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

{% endtab %}
{% endtabs %}

### Curl Example

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

## Annotate Structural Variants

<mark style="color:blue;">`GET`</mark> `ttps://www.oncokb.org/api/v1/annotate/structuralVariants`                      &#x20;

#### 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 |

{% tabs %}
{% tab title="200 Annotate structural variants successfully." %}

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

{% endtab %}
{% endtabs %}

### Curl Example

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

<mark style="color:blue;">`GET`</mark> `https://www.oncokb.org/api/v1/annotate/mutations/byGenomicChange`                              &#x20;

#### 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. |

{% tabs %}
{% tab title="200 Annotated mutations by genomic change successfully. " %}

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

{% endtab %}
{% endtabs %}

### Curl Example

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

## Annotate Mutations by HGVSg

<mark style="color:blue;">`GET`</mark> `ttps://www.oncokb.org/api/v1/annotate/mutations/byHGVSg`                      &#x20;

#### 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 |

{% tabs %}
{% tab title="200 Annotate mutations by HGVSg successfully." %}

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

{% endtab %}
{% endtabs %}

### Curl Example

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

1. The `evidenceType`field 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.