OncoKB reader service: API reference

Research use only. Answers are read from oncokb.org with logged-in web accounts and are not for clinical reporting without review. Every annotation carries "research_only": true. The terms that apply are in the guide.

This document describes version 4.0.0 with its default backend, wire: the service makes the same JSON calls the oncokb.org pages make, with a plain HTTP client. There is no browser. The old browser backend still exists as a fallback; what differs there is listed in Browser backend.

TLS. Since 2026-11-10 the server answers on https://3-105-9-242.sslip.io (plain HTTP redirects). The address is a Lightsail static IP, so it does not change when the instance is stopped and started.

Contents

1. Quick start
2. Conventions
3. Endpoints at a glance
4. Annotate one variant
5. The annotation response
6. Batch
7. Sample
8. Reference data
9. Jobs
10. Lab files
11. Artifacts
12. Operations endpoints
13. Accounts and usage
14. Error codes
15. Warnings
16. Limits
17. Client examples
18. Browser backend

Quick start

export B=https://3-105-9-242.sslip.io
export K=<your key>          # ask the service owner

curl -s $B/ready                                      # can it answer?
curl -s -X POST $B/api/v1/annotate \
  -H "X-API-Key: $K" -H 'Content-Type: application/json' \
  -d '{"gene":"IDH1","alteration":"R132S","tumor_type":"AML"}'

Conventions

Authentication

Send X-API-Key: <key> on every /api/v1/* and /admin/* call. A missing or wrong key gets 401 UNAUTHORIZED. /health, /ready, /, /reference, /docs and /openapi.json are open. There is one shared key for all callers and for the admin endpoints; there are no per-user keys. If the service was started without ONCOKB_SVC_API_KEY, no key is checked at all.

Headers

Every answer has an X-Request-ID. The service logs one line per request with that id, the method, the path, the status and the time taken. The query string is not logged. Quote the id when reporting a problem.

Browsers on other origins can call the API only if the owner listed the origin in ONCOKB_SVC_CORS_ORIGINS. By default no origin is allowed.

HTTP status

A 200 does not mean OncoKB curated the variant. Always read status.

Error body

Every 4xx and 5xx has the same shape:

{"status": "invalid",
 "errors": [{"code": "UNKNOWN_TUMOR_TYPE", "message": "'AMLL' is not an OncoTree code or name", "field": "tumor_type",
             "suggestions": ["AML (Acute Myeloid Leukemia)", "TAML (Therapy-Related Acute Myeloid Leukemia)"]}]}

errors[].code is stable; program against it, not against message. Only code is always present: message, field, retryable, suggestions and hint appear when they apply. An annotation call whose body passed the schema check also returns client_ref. Errors raised outside annotation (401, 404, 405, 409, 413, and the 422s of the sample, upload and account endpoints) also carry the older detail field: the same object as errors[0], or a plain string for an unknown route or a wrong method.

Where an answer comes from

A lookup is answered from the first of these that applies:

1. The Cancer Gene List. A gene OncoKB does not annotate is answered locally with GENE_NOT_ANNOTATED_BY_ONCOKB. Nothing is sent to oncokb.org. The service does this only while it holds oncokb.org's own gene list for the data version in use (cancer_gene_list.current in /health); otherwise the lookup is sent.
2. The store. The service keeps the JSON oncokb.org sent for each lookup. A stored answer is reused for as long as OncoKB's data version is unchanged, and for at most 45 days. Nothing is sent to oncokb.org; provenance.cached is true.
3. oncokb.org. One HTTP GET on one account. provenance.cached is false and provenance.wire_bytes says what it cost.

What is stored is the site's JSON, not the response. Each response is built again on every request, so the same stored lookup can be returned with a different detail, and a fix to the response builder needs no new download. The store key is the gene, the alteration, the reference genome and the tumour type: the same variant under another tumour type is another lookup. Two identical lookups that arrive at the same time share one download.

Measured on 2026-11-10 (OncoKB data v7.7): one lookup is 1.3-49 KB gzip on the wire, 4.6 KB on average over 81 myeloid-panel lookups. A 40-finding solid-tumour sample with tumour types took 668 KB in total (16.5 KB per lookup) and 17.3 s on one account; the same 40 again took 0.07 s and no bytes.

Retrying

Retry only when errors[].retryable is true, with a growing wait (for example 5 s, 20 s, 80 s). Before it answers 503 the service has already made up to 4 attempts: it moves to another account after a 429, a 5xx or a 403, repeats once on the same account after a failed connection, and logs in again once after a 401. When every account has answered 429 or 5xx (always the case with one account), it waits out the shortest account interval and tries again. An answer over the size limit and a 400 from oncokb.org are not tried again. A failed download stores nothing, so a retry asks oncokb.org again.

Endpoints at a glance

Annotate one variant

POST /api/v1/annotate

Request body

One of alteration, fusion_partner, copy_number_type or genomic_coordinates is needed, unless gene is written A::B, which is itself the fusion. One request is one finding: fusion_partner together with an alteration that is not the fusion itself is rejected with VARIANT_TYPE_CONFLICT; send the fusion and the mutation as two requests. Unknown fields are rejected. Blank strings count as missing. No field has a clinical default.

detail, force_refresh and generate_pdf may also be sent at the top level; a value under options wins.

Forms of input

A fusion is asked under each partner gene, the 3' partner first; an immunoglobulin partner (IGH, IGK, IGL) is not asked. The first answer in which OncoKB curates the fusion is returned; failing that, the first annotated one; failing that, the last one. gene.hugo_symbol names the partner whose answer was returned. query.gene is the partner asked first, and query.fusion_genes keeps both.

The full normalisation rules (amino-acid forms, named alterations, what is rejected and why) are in the guide.

Genomic coordinates

{"gene": "BRAF", "tumor_type": "MEL",
 "genomic_coordinates": {"chromosome": "7", "position": 140753336, "reference": "A", "alternate": "T", "genome_build": "GRCh38"}}

Use this for VCF lines, splice sites, start loss and p.?. It is one lookup: oncokb.org maps the change onto its own canonical transcript and annotates it in the same answer.

gene, if also given, is a hint and is not sent to oncokb.org. It has two effects. If the hint is a gene OncoKB does not annotate, the answer is not_found with GENE_NOT_ANNOTATED_BY_ONCOKB and nothing is asked, so send a hint only when it comes from your own annotation of that position. If OncoKB maps the change to another gene, the answer carries the warning gene_hint_differs:A->B.

In the response, query.gene and query.alteration hold what OncoKB mapped the change to, query.genomic_change holds the change as sent to OncoKB (chromosome,start,end,ref,alt and the build), and provenance.resolved_via holds the oncokb.org genomic-change page for it.

Germline lookups

With germline: true the lookup goes to OncoKB's germline annotation. OncoKB names germline variants by their cDNA change and matches the name exactly, so:

curl -s -X POST $B/api/v1/annotate -H "X-API-Key: $K" -H 'Content-Type: application/json' \
  -d '{"gene":"BRCA1","alteration":"c.68_69del","germline":true}'

The response has a germline block.

Query-string form

GET /api/v1/annotate takes the same input as query parameters. It has no genomic_coordinates and no client_ref.

curl -s "$B/api/v1/annotate?gene=IDH1&alteration=R132S&tumor_type=AML&detail=summary" -H "X-API-Key: $K"

Status codes

Example

Request:

curl -s -X POST $B/api/v1/annotate -H "X-API-Key: $K" -H 'Content-Type: application/json' \
  -d '{"gene":"IDH1","alteration":"R132S","tumor_type":"AML","client_ref":"S1-v1"}'

Response, built from oncokb.org's JSON of 2026-11-10 (long texts and lists shortened with ...). This example was produced against the test stand-in for oncokb.org, which answers at once, hence fetch_ms: 1:

{
 "status": "annotated",
 "research_only": true,
 "warnings": [],
 "errors": [],
 "provenance": {
  "source": "oncokb.org web API (variantAnnotation)",
  "page_url": "https://www.oncokb.org/gene/IDH1/somatic/R132S/AML",
  "page_title": null,
  "oncokb_data_version": "v7.7",
  "oncokb_last_data_update": "10/29/2026",
  "parser_version": "4.0.0",
  "service_version": "4.0.0",
  "backend": "wire",
  "cached": false,
  "retrieved_at": "2026-11-10T09:38:17+00:00",
  "cache_age_s": 0,
  "wire_bytes": 6623,
  "fetch_ms": 1,
  "account": "default",
  "load_ms": 1,
  "cache_stored": true
 },
 "gene": {
  "hugo_symbol": "IDH1",
  "gene_summary": "IDH1, a cell metabolism enzyme, is recurrently mutated in various cancer types including acute myelo...",
  "gene_type": "ONCOGENE",
  "oncogene": true,
  "tumor_suppressor": false,
  "entrez_gene_id": 3417,
  "background": "The IDH1 (isocitrate dehydrogenase 1) protein is an enzyme that catalyzes the oxidative decarboxylat...",
  "transcripts": {
   "grch37": {"isoform": "ENST00000345146", "refseq": "NM_005896.2"},
   "grch38": {"isoform": "ENST00000345146", "refseq": "NM_005896.2"}
  }
 },
 "variant": {
  "canonical_alteration": "R132S",
  "oncokb_alteration": "R132S",
  "variant_summary": "The IDH1 R132S mutation is likely oncogenic.",
  "hotspot": true,
  "curated_in_oncokb": true,
  "vus": false,
  "allele_exist": true,
  "vue": false,
  "consequence": "missense_variant",
  "protein_start": 132,
  "protein_end": 132,
  "last_evidence_update": "07/24/2026",
  "match": {"exact_row_present": true, "oncokb_alteration_curated": true, "basis": "exact"}
 },
 "oncogenicity": {"status": "Likely Oncogenic"},
 "mutation_effect": {
  "known_effect": "Switch-of-function",
  "description": "The IDH1 R132S mutation is located in the catalytic site of the IDH1 protein. This mutation has been...",
  "pmids": ["21760534", "29670690", "..."],
  "abstracts": []
 },
 "evidence": {
  "highest_sensitive_level": "Level 1",
  "highest_resistance_level": null,
  "highest_diagnostic_level": "Level Dx2",
  "highest_prognostic_level": null,
  "highest_fda_level": "Level Fda2",
  "oncokb_highest_levels": {"sensitive": "Level 1", "resistance": null, "diagnostic": "Level Dx2",
                            "prognostic": null, "fda": "Level Fda2"},
  "other_tumor_type_levels": [
   {"level": "Level 3B", "cancer_type": "Myelodysplastic Syndromes"},
   {"level": "Level Fda3", "cancer_type": "Myelodysplastic Syndromes"}
  ],
  "treatments": [
   {
    "level": "Level 1",
    "tier": "standard_care",
    "regimen": "Ivosidenib",
    "drugs": ["Ivosidenib"],
    "matched_alterations": ["R132C", "R132H", "..."],
    "match_type": "exact",
    "level_associated_cancer_types": ["Acute Myeloid Leukemia"],
    "excluded_cancer_types": [],
    "in_query_tumor_type": true,
    "citation_count": 6,
    "pmids": ["29860938", "23393090", "..."],
    "abstracts": [
     {"abstract": "Dohner et al. Abstract# 7042, ASCO 2022.",
      "link": "https://ascopubs.org/doi/abs/10.1200/JCO.2022.40.16_suppl.7042"},
     "..."
    ],
    "description": "Ivosidenib is a small molecule inhibitor of mutant IDH1 that is FDA-approved for adult patients with...",
    "evidence_id": 26867,
    "fda_level": "Level Fda2",
    "response": "sensitivity",
    "approved_indications": [],
    "drugs_detail": [{"name": "Ivosidenib", "ncit_code": "C114383"}]
   },
   "..."
  ],
  "diagnostic": [
   {
    "level": "Level Dx2",
    "matched_alterations": ["Oncogenic Mutations"],
    "match_type": "generic",
    "level_associated_cancer_types": ["Acute Myeloid Leukemia"],
    "excluded_cancer_types": [],
    "in_query_tumor_type": true,
    "citation_count": 7,
    "pmids": ["22397365", "19657110", "..."],
    "abstracts": [],
    "description": "This assertion is supported by (PMID: 22417203, 20538800, 22397365, 20097881, 20368543, 19657110, 20...",
    "evidence_id": 26814
   }
  ],
  "prognostic": [],
  "fda": [
   {"level": "Level Fda2", "matched_alterations": ["R132S"],
    "level_associated_cancer_types": ["Acute Myeloid Leukemia"], "excluded_cancer_types": [], "in_query_tumor_type": true},
   {"level": "Level Fda3", "matched_alterations": ["Oncogenic Mutations"],
    "level_associated_cancer_types": ["Myelodysplastic Syndromes"], "excluded_cancer_types": [], "in_query_tumor_type": false}
  ],
  "summaries": {
   "therapeutic": "The IDH1-targeted inhibitors ivosidenib and olutasidenib are FDA-approved for the treatment of patie...",
   "diagnostic": "The presence of an IDH1 R132S mutation supports a diagnosis of acute myeloid leukemia.",
   "prognostic": null,
   "fda": "Tumor type-specific IDH1 alterations and the corresponding FDA Level of Evidence assigning their cli..."
  }
 },
 "query": {
  "gene_input": "IDH1",
  "alteration_input": "R132S",
  "tumor_type_input": "AML",
  "gene": "IDH1",
  "alteration": "R132S",
  "variant_type": "snv_indel",
  "fusion_genes": null,
  "oncotree_code": "AML",
  "oncotree_name": "Acute Myeloid Leukemia",
  "reference_genome": "GRCh37"
 },
 "artifacts": {"pdf_available": false, "pdf_url": null},
 "client_ref": "S1-v1"
}

The annotation response

Which blocks are present

Top level

query

provenance

For a fusion asked under two partner genes, wire_bytes, fetch_ms, account and cached describe the lookup whose answer was returned.

Answers that have a provenance but no gene block (see Which blocks are present) have a shorter one: no page_title, oncokb_last_data_update or parser_version, and oncokb_data_version is null unless oncokb.org answered.

gene

variant

oncogenicity, mutation_effect

evidence

In a pan-cancer query (no tumor_type) a row counts as in the query tumour type only when OncoKB wrote it for All Tumors, All Solid Tumors, All Liquid Tumors or All Pediatric Tumors. The five highest_*_level fields are therefore usually null; read oncokb_highest_levels and the rows.

Evidence rows

Fields of treatments[], diagnostic[] and prognostic[] rows:

Fields of fda[] rows: level (Level Fda1-Fda3), matched_alterations[] (one name), level_associated_cancer_types[], excluded_cancer_types[], in_query_tumor_type. There is one row per alteration and cancer type, with the highest FDA level. FDA rows have no match_type.

Citations and the description of a row come from that row's own evidence. Version 3.2.0 joined them by level and drug, which could mix cancer types.

Order of treatments[]:

• With a tumour type: per drug combination only its highest level is listed. Standard care comes first, then investigational; each group is sorted by level, then drug name. Rows written for other tumour types are included with in_query_tumor_type: false.
• Without one: every row, sorted by level, alterations, cancer types, drugs.

Read match_type. A Level 1 reached through a generic row is weaker evidence for your exact variant than the level alone suggests.

Pass the real diagnosis. The highest_*_level fields cover only the rows for the tumour type you send. When the diagnosis is not settled, omit tumor_type and read the rows.

germline

Present only when the request had germline: true.

In a germline answer oncogenicity.status is null, status is annotated when OncoKB gives a pathogenicity call or curates the variant, and variant.match.basis is exact only when the variant is curated.

artifacts

{"pdf_available": false, "pdf_url": null} on the wire backend, always.

Detail levels

summary keeps levels, drugs, cancer types, PubMed ids, gene_summary, variant_summary and evidence.summaries. For IDH1 R132S in AML the three bodies are about 5 KB (summary), 13 KB (standard) and 17 KB (full) of JSON. The level changes the response only. It does not change what is downloaded or stored.

Batch

POST /api/v1/annotate/batch

curl -s -X POST $B/api/v1/annotate/batch -H "X-API-Key: $K" -H 'Content-Type: application/json' \
  -d '{"items":[{"gene":"IDH1","alteration":"R132S","tumor_type":"AML","client_ref":"a"},
                {"gene":"IDH1","client_ref":"b"},
                {"gene":"TTN","alteration":"R100C","client_ref":"c"}]}'

{"counts": {"annotated": 1, "invalid": 1, "not_found": 1},
 "results": [{"status": "annotated", "client_ref": "a", "...": "..."},
             {"status": "invalid", "client_ref": "b",
              "errors": [{"code": "MISSING_ALTERATION", "message": "alteration (or copy_number_type / fusion_partner) is required", "field": "alteration"}]},
             {"status": "not_found", "client_ref": "c", "...": "..."}]}

Items are worked on 64 at a time (ONCOKB_JOB_PARALLEL) and the answer is sent when all are done. For more than 100 variants use a job.

Sample

POST /api/v1/sample annotates every finding of one tumour sample in one call and leads the answer with a summary for a report.

Request body

Each entry of variants:

An entry has no tumor_type, variant_type or options of its own; sending one is rejected with INVALID_REQUEST.

A sample holds 1 to 500 findings, variants and biomarkers together. An empty sample gets 422 EMPTY_SAMPLE; more than 500 gets 422 SAMPLE_TOO_LARGE. An unknown tumor_type gets 422 UNKNOWN_TUMOR_TYPE for the whole sample, before anything is looked up.

Response

findings[] rows:

summary:

Each therapy or resistance row is {regimen, level, response, fda_level, finding, matched_alterations, cancer_types, pmids}; response is sensitivity or resistance. A drug that appears for two findings is listed once per finding. Resistance evidence is never listed among the therapies. Without a tumor_type nearly every row lands in the two ..._other_tumor_types lists.

Example

curl -s -X POST $B/api/v1/sample -H "X-API-Key: $K" -H 'Content-Type: application/json' -d '{
  "sample_id": "S-001", "assay": "myeloid panel", "tumor_type": "AML", "options": {"detail": "summary"},
  "variants": [{"gene": "IDH1", "alteration": "R132S", "vaf": 0.31, "client_ref": "v1"},
               {"gene": "FLT3", "alteration": "ITD"},
               {"gene": "TP53", "alteration": "H368N", "vaf": 0.4},
               {"gene": "TTN", "alteration": "R100C"}]}'

Response (lists shortened with ...). In this run IDH1 R132S was already in the store and TTN was answered from the Cancer Gene List, hence answered_from_store: 2:

{
 "sample_id": "S-001",
 "assay": "myeloid panel",
 "tumor_type": {"input": "AML", "oncotree_code": "AML", "oncotree_name": "Acute Myeloid Leukemia"},
 "research_only": true,
 "counts": {"annotated": 2, "not_curated": 1, "not_found": 1},
 "summary": {
  "actionable_findings": [
   {"index": 1, "client_ref": "1", "finding": "FLT3 ITD", "status": "annotated", "oncogenicity": "Oncogenic",
    "mutation_effect": "Gain-of-function", "hotspot": false, "pathogenicity": null,
    "highest_sensitive_level": "Level 1", "highest_resistance_level": null, "highest_diagnostic_level": "Level Dx2",
    "highest_prognostic_level": "Level Px1", "highest_fda_level": "Level Fda2", "vaf": null, "errors": []},
   {"index": 0, "client_ref": "v1", "finding": "IDH1 R132S", "status": "annotated", "oncogenicity": "Likely Oncogenic",
    "mutation_effect": "Switch-of-function", "hotspot": true, "pathogenicity": null,
    "highest_sensitive_level": "Level 1", "highest_resistance_level": null, "highest_diagnostic_level": "Level Dx2",
    "highest_prognostic_level": null, "highest_fda_level": "Level Fda2", "vaf": 0.31, "errors": []}
  ],
  "oncogenic_findings": ["IDH1 R132S", "FLT3 ITD"],
  "therapies_in_tumor_type": [
   {"regimen": "Gilteritinib", "level": "Level 1", "response": "sensitivity", "fda_level": "Level Fda2", "finding": "FLT3 ITD",
    "matched_alterations": ["D835", "Internal Tandem Duplication", "..."],
    "cancer_types": ["Acute Myeloid Leukemia"], "pmids": ["31665578", "28645776", "..."]},
   {"regimen": "Ivosidenib", "level": "Level 1", "response": "sensitivity", "fda_level": "Level Fda2", "finding": "IDH1 R132S",
    "matched_alterations": ["R132C", "R132H", "..."],
    "cancer_types": ["Acute Myeloid Leukemia"], "pmids": ["29860938", "23393090", "..."]},
   "..."
  ],
  "resistance_in_tumor_type": [],
  "therapies_in_other_tumor_types": [
   {"regimen": "Olutasidenib + Azacitidine Regimen", "level": "Level 3B", "response": "sensitivity", "fda_level": "Level Fda3",
    "finding": "IDH1 R132S",
    "matched_alterations": ["Oncogenic Mutations"], "cancer_types": ["Myelodysplastic Syndromes"], "pmids": ["40457853"]}
  ],
  "resistance_in_other_tumor_types": [],
  "diagnostic": [
   {"level": "Level Dx2", "finding": "IDH1 R132S", "cancer_types": ["Acute Myeloid Leukemia"], "pmids": ["22397365", "..."]},
   {"level": "Level Dx2", "finding": "FLT3 ITD", "cancer_types": ["Acute Myeloid Leukemia"], "pmids": ["18450602", "..."]}
  ],
  "prognostic": [
   {"level": "Level Px1", "finding": "FLT3 ITD", "cancer_types": ["Acute Myeloid Leukemia"], "pmids": ["15746041", "..."]}
  ],
  "not_read": []
 },
 "findings": ["... 4 rows, same fields as actionable_findings ..."],
 "results": ["... 4 annotation responses ..."],
 "provenance": {"service_version": "4.0.0", "items": 4, "answered_from_store": 2, "wire_bytes": 12456,
                "oncokb_data_version": "v7.7"}
}

Reference data

GET /api/v1/info

The OncoKB data version the stored answers belong to. No parameters.

{"service_version": "4.0.0", "parser_version": "4.0.0", "backend": "wire",
 "oncokb": {"data_version": "v7.7", "data_date": "10/29/2026", "app_version": "v6.12.0",
            "oncotree_version": "oncotree_2025_10_03", "checked_at": "2026-11-10T09:38:17+00:00"},
 "cancer_gene_list": {"date": "10/29/2026 (v7.7)", "source": "oncokb.org cancerGeneList (live)", "annotated_genes": 1040,
                      "current": true}}

Status codes: 200, 401.

GET /api/v1/genes

OncoKB's Cancer Gene List. Nothing is downloaded per call.

curl -s "$B/api/v1/genes" -H "X-API-Key: $K"

{"source": "oncokb.org cancerGeneList (live)", "list_date": "10/29/2026 (v7.7)", "count": 1040,
 "genes": [{"hugo_symbol": "A1CF", "entrez_gene_id": 29974, "gene_type": "ONCOGENE", "oncokb_annotated": true,
            "grch37_isoform": "ENST00000373993", "grch38_isoform": "ENST00000373993", "msk_impact": false, "msk_heme": false},
           "..."]}

Rows are sorted by symbol. Until the live list has been read, the rows come from the bundled snapshot and hold hugo_symbol and oncokb_annotated only.

Status codes: 200, 401.

GET /api/v1/genes/{symbol}

One gene. The symbol is not case-sensitive, and an alias OncoKB lists resolves to its gene.

curl -s "$B/api/v1/genes/BRAF?variants=true" -H "X-API-Key: $K"

{"hugo_symbol": "BRAF", "entrez_gene_id": 673, "gene_type": "ONCOGENE", "oncokb_annotated": true, "aliases": ["BRAF1"],
 "transcripts": {"grch37": {"isoform": "ENST00000288602", "refseq": "NM_004333.4"},
                 "grch38": {"isoform": "ENST00000646891", "refseq": "NM_004333.4"}},
 "in_panels": {"msk_impact": true, "msk_heme": true, "foundation_one": true, "foundation_heme": true,
               "vogelstein": true, "sanger_cgc": true},
 "provenance": {"source": "oncokb.org cancerGeneList (live)", "oncokb_data_version": "v7.7",
                "page_url": "https://www.oncokb.org/gene/BRAF", "cached": false, "wire_bytes": 52307},
 "annotated_alterations": [
  {"alteration": "K601N", "oncogenicity": "Oncogenic", "mutation_effect": "Gain-of-function",
   "pmids": ["26732095", "..."], "description": "The class II BRAF K601N mutation is located in the kinase domain..."},
  "..."],
 "clinical_alterations": [
  {"alteration": "V600", "level": "Level 3A", "fda_level": "Level Fda3", "drugs": ["Vemurafenib", "Dabrafenib"],
   "cancer_types": ["Histiocytosis"], "excluded_cancer_types": [], "pmids": ["31213430", "..."],
   "description": "Vemurafenib is an orally available, small molecule RAF-targeted inhibitor..."},
  "..."]}

The record costs no download. With variants=true the two tables are two downloads per gene and OncoKB data version; after that they come from the store. For a gene OncoKB does not annotate, the tables are left out.

This endpoint needs the live Cancer Gene List. Until the service has read it (a few seconds after a start, and again after an OncoKB data release), every symbol answers 503 GENE_LIST_NOT_LOADED, which is retryable.

Jobs

Submit a variant list: POST /api/v1/jobs

Answers at once with HTTP 202:

{"job_id": "8f2c1a0b9d3e4f56", "status": "running", "total": 300, "poll": "/api/v1/jobs/8f2c1a0b9d3e4f56"}

Status codes: 202, 401, 422 (INVALID_REQUEST).

Progress and results: GET /api/v1/jobs/{id}

offset and limit apply to variant jobs only.

curl -s "$B/api/v1/jobs/8f2c1a0b9d3e4f56" -H "X-API-Key: $K"                      # progress
curl -s "$B/api/v1/jobs/8f2c1a0b9d3e4f56?offset=0&limit=500" -H "X-API-Key: $K"   # first page of results

{"id": "8f2c1a0b9d3e4f56", "kind": "variants", "status": "done", "total": 2, "done": 2, "counts": {"annotated": 2},
 "submitted_at": "2026-11-10T09:40:02+00:00", "finished_at": "2026-11-10T09:40:04+00:00"}

Poll every few seconds. A restart of the service marks running jobs failed; nothing resumes on its own, so submit the job again. For file jobs error then reads "service restarted during the job; submit it again".

Status codes: 200, 401, 404 (NOT_FOUND).

Delete: DELETE /api/v1/jobs/{id}

Removes a finished job and its results and answers {"deleted": "<id>"}. An unknown or still running job gets 404 NOT_FOUND_OR_RUNNING. Delete file jobs when you have the report, because they hold patient-derived variants. Finished jobs older than 30 days are removed when the next job is submitted.

Status codes: 200, 401, 404.

Lab files

Both uploads return a job at once (HTTP 202):

{"job_id": "5b1e77c2a9d04f13", "status": "running", "poll": "/api/v1/jobs/5b1e77c2a9d04f13",
 "report": "/api/v1/jobs/5b1e77c2a9d04f13/report", "tsv": "/api/v1/jobs/5b1e77c2a9d04f13/report.tsv"}

Poll poll until status is done or failed, then fetch the report. The uploaded file is deleted when the job ends. See the guide for what the filters do and why.

Thermo Ion Reporter: POST /api/v1/oncomine

Multipart form:

curl -s -X POST $B/api/v1/oncomine -H "X-API-Key: $K" \
  -F "files=@011026_1_selected_variants.tsv" -F "files=@011026_2_selected_variants.tsv" -F "tumor_type=AML"

A full (unselected) export is filtered the way Ion Reporter does (thermo_like_v1); a lab-selected export is taken as it is. A protein change that OncoKB rejects on its own transcript is asked again by its hg19 position; the row then carries the warning oncomine_transcript_differs:A->B.

Illumina VCF: POST /api/v1/vcf

Multipart form:

curl -s -X POST $B/api/v1/vcf -H "X-API-Key: $K" -F "file=@sample.hard-filtered.vcf.gz" -F "mode=germline"
curl -s -X POST $B/api/v1/vcf -H "X-API-Key: $K" -F "file=@tumour.vcf.gz" -F "mode=somatic" \
  -F "tumor_type=NSCLC" -F "min_vaf=0.05" -F "min_depth=50"

What the job does: it keeps calls with FILTER PASS or . in the coding sequence (plus 2 bp of splice site) of OncoKB-annotated genes (HLA and KIR genes are skipped), works out the consequence on the MANE Select transcript, and removes common gnomAD v4.1 polymorphisms. SNVs are asked by protein change with reference_genome: GRCh38; indels, multi-base substitutions and splice sites by genomic coordinates; the two TERT promoter hotspots as Promoter Mutation. A protein change that OncoKB rejects is asked again by coordinates and gets the warning mane_transcript_differs_from_oncokb.

The job needs the reference files (MANE v1.5 and the gnomAD v4.1 subset) on the server. Without them the job ends failed and error names the missing file. The job also ends failed, with nothing annotated, when at least 5 coding SNVs, and more than 5 % of all coding SNVs, do not match the GRCh38 reference base: the file is then not on GRCh38.

Germline caveat. OncoKB's somatic annotation describes what a variant does in a tumour. On a germline genome it means "would be oncogenic if somatic", not inherited risk. The germline_* columns hold OncoKB's germline annotation where it has one. Germline classification belongs to ClinVar / ACMG.

Report as JSON: GET /api/v1/jobs/{id}/report

Every report starts with job_id, kind and params.

Oncomine report: samples[] and summary[].

oncokb is a short form of the annotation: status, oncokb_gene, oncokb_alteration, oncogenicity, mutation_effect, hotspot, highest_sensitive, highest_resistance, highest_diagnostic, highest_prognostic, levels_any_tumor[], errors[] (codes), warnings[], page. levels_any_tumor lists every level found in the treatment, diagnostic and prognostic rows, whatever the tumour type.

vaf is in percent, as in the export. flags[] can hold possible_germline:vaf=N, in_population_databases:af=N, low_level_amplification:cn=N, single_copy_loss_not_queried:cn=N, splice_site_via_coordinates and lab_selected_outside_filter:.... A variant that was kept but not asked (a one-copy loss) has oncokb: null.

summary[] has one row per kept variant with the columns of the TSV below.

VCF report:

Fields of calls[]: origin, gene, chrom, pos, ref, alt, mane (the MANE Select transcript), consequence, protein_mane, genotype, vaf, depth, gnomad_class, gnomad_drop, gnomad_filtering_af, gnomad_af, gnomad_grpmax, gnomad_nhomalt, gnomad_filter, the short annotation fields listed above for oncokb, and oncokb_full with full=true. Calls for which the germline annotation was asked also have germline_status, germline_pathogenicity, germline_penetrance and germline_inheritance[].

Rows are ordered: asked calls before not_queried, mosaic calls first, then by oncogenicity, then by gene.

Report as TSV: GET /api/v1/jobs/{id}/report.tsv

text/tab-separated-values, sent as an attachment named <job_id>.tsv. The first line holds the column names. A list is written with commas between its items. A null or missing value is an empty cell. Status codes are the same as for the JSON report.

Oncomine jobs: one row per kept variant of every sample (biomarkers are in the JSON report only). Columns, in order (tab-separated in the file):

sample  assay  label  vaf  status  oncokb_gene  oncokb_alteration  oncogenicity  mutation_effect  hotspot
highest_sensitive  highest_resistance  highest_diagnostic  highest_prognostic  levels_any_tumor  errors  flags

VCF jobs: one row per coding call, including the calls not asked. Columns, in order (tab-separated in the file):

origin  gene  chrom  pos  ref  alt  consequence  protein_mane  genotype  vaf  depth
gnomad_class  gnomad_filtering_af  gnomad_af  gnomad_grpmax  gnomad_nhomalt
status  oncokb_alteration  oncogenicity  mutation_effect  hotspot  highest_sensitive  highest_resistance
levels_any_tumor  germline_pathogenicity  germline_penetrance  germline_inheritance  errors

curl -s $B/api/v1/jobs/5b1e77c2a9d04f13/report.tsv -H "X-API-Key: $K" -o report.tsv

Artifacts

GET /api/v1/artifacts/pdf/{name}

Downloads a PDF of an OncoKB page (application/pdf). Only the browser backend makes PDFs, when a request has generate_pdf: true; the response then names the file in artifacts.pdf_url. The wire backend never makes one, so on the wire backend this endpoint answers 404 NOT_FOUND unless the file is left over from the browser backend.

Status codes: 200, 401, 404.

Operations endpoints

GET /ready

For monitors, load balancers and deploys. 200 when the service has started and at least one account can carry a request; otherwise 503. No key needed.

{"ready": true, "reasons": [], "service_version": "4.0.0", "parser_version": "4.0.0", "backend": "wire"}

ready: true says an account is available. It does not prove that oncokb.org answers at this moment, and an account that has yet to log in counts as available.

GET /health

200 while the process runs, whatever the state of oncokb.org, so it proves liveness only. No key needed. Account names, tokens and proxy credentials never appear here.

Example for one account at default pacing. The numbers are illustrative:

{
 "status": "ok", "service_version": "4.0.0", "parser_version": "4.0.0", "backend": "wire", "started": true,
 "accounts": {"configured": 1, "usable": 1, "states": {"ready": 1}, "inflight": 0, "capacity": 3, "with_proxy": 0,
              "requests_per_s_ceiling": 2.5},
 "oncokb": {"data_version": "v7.7", "data_date": "10/29/2026", "app_version": "v6.12.0",
            "oncotree_version": "oncotree_2025_10_03", "checked_at": "2026-11-10T09:38:17+00:00"},
 "lookups": {"lookups": 16, "from_store": 6, "fetched": 12, "shared": 0, "retries": 0, "logins": 0,
             "login_failures": 0, "errors": 0, "prefiltered": 3},
 "traffic": {"requests": 13, "bytes_down": 125276, "bytes_up": 3525, "mb_total": 0.129, "connections": 2,
             "avg_kb_per_request": 9.6, "downloads_cut_short": 1, "connections_retired": 1,
             "mb_not_downloaded_thanks_to_store": 0.04, "since": "2026-11-10T09:38:17+00:00"},
 "store": {"data_version": "v7.7", "entries": 12, "disk_bytes": 119172, "hits": 6, "misses": 12, "stale": 0,
           "stored": 12, "bytes_saved": 39738,
           "by_kind": {"va": {"entries": 9, "disk_bytes": 66585, "wire_bytes": 70764}, "...": {}}},
 "require_proxy": false,
 "cancer_gene_list": {"date": "10/29/2026 (v7.7)", "source": "oncokb.org cancerGeneList (live)", "annotated_genes": 1040,
                      "current": true},
 "last_error": null,
 "login_configured": true, "memory_mb": 54, "memory_high_mb": 2600, "jobs_running": 0
}

POST /admin/cache/purge

Empties the store, the stored Cancer Gene List included, and returns {"purged": <number of entries>}. Every later lookup is downloaded again. This is not needed after an OncoKB data release: the service notices the new data version and drops the old answers itself. To refresh one answer, send force_refresh instead.

Status codes: 200, 401.

Accounts and usage

The service reads oncokb.org with one or more web accounts. Each account has its own pacing and, optionally, its own proxy, and always leaves through that proxy. Passwords, tokens and proxy credentials are write-only: no endpoint returns them. These endpoints exist on the wire backend only; on the browser backend they answer 404 NOT_AVAILABLE_IN_BROWSER_BACKEND.

GET /admin/accounts

{"summary": {"configured": 1, "usable": 1, "states": {"ready": 1}, "inflight": 0, "capacity": 3, "with_proxy": 0,
             "requests_per_s_ceiling": 2.5},
 "loaded_at": "2026-11-10T09:38:17+00:00",
 "accounts": [
  {"id": "default", "username": "u***@example.org", "status": "ready", "enabled": true, "proxy": null,
   "has_password": true, "has_token": true, "token_expires_at": "2027-05-04T10:12:44Z",
   "token_checked_at": "2026-11-10T09:38:20+00:00", "token_renewal": null,
   "max_concurrency": 3, "min_interval_s": 0.4, "interval_s": 0.4, "daily_limit": 0, "requests_today": 13,
   "inflight": 0, "cooldown_s": 0, "last_login_at": "2026-11-10T09:38:19+00:00", "last_error": null, "note": "",
   "totals": {"requests": 13, "ok": 13, "errors": 0, "throttled": 0, "unauthorized": 0, "logins": 1,
              "login_failures": 0, "bytes_down": 125276, "bytes_up": 3525}}]}

The values in this example are illustrative. summary is the accounts block of /health. loaded_at is when the accounts file was last read. Each row:

An account rests after a refused login (15 minutes), a 403 (1 hour), or when oncokb.org or the proxy cannot be reached (1 minute; after a login that cannot connect, or after one lookup fails to connect twice). A login also counts as refused when oncokb.org accepts the password and then rejects the token it hands out. The rest doubles with each failure in a row, up to 6 hours. A success resets it, and so does POST /admin/accounts/{id}/login.

Status codes: 200, 401, 404 (browser backend).

POST /admin/accounts

Adds an account, or changes a known one, and rewrites the accounts file. The account changed is the one with this id; without an id, the one with this username. Fields left out of a change keep their stored value.

The defaults in this table apply to a new account. A change keeps the account's token and counters. A new password or a new proxy ends a rest period the old one caused. The default account takes its e-mail and password from the environment: its other settings can be changed here, its login cannot.

curl -s -X POST $B/admin/accounts -H "X-API-Key: $K" -H 'Content-Type: application/json' \
  -d '{"id":"lab2","username":"second@example.org","password":"<password>",
       "proxy":"http://<user>:<pass>@proxy.example.net:8000","daily_limit":3000}'

{"account": {"id": "lab2", "username": "s***@example.org", "status": "ready", "proxy": "http://proxy.example.net:8000", "...": "..."},
 "logged_in": true}

logged_in is true or false after a login attempt, and null when none was made (login=false, a disabled account, no password, or the account already holds a token and its password did not change). After a refused login the account's status is cooldown:login_failed and last_error holds oncokb.org's reason.

POST /admin/accounts/reload

Re-reads the accounts file after it was edited by hand. An account already known (same id, same login) keeps its token, counters and pacing state. New accounts log in on first use. Accounts no longer in the file are removed. The default account always takes its e-mail and password from the environment, whatever the file says.

{"accounts": 3, "added": ["lab3"], "removed": [], "enabled": 3, "with_proxy": 2}

Status codes: 200, 401, 404 (browser backend), 422 INVALID_ACCOUNTS_FILE (the file does not parse; nothing changed).

POST /admin/accounts/{id}/login

Ends any rest period of the account and logs it in now, even if it holds a token. Use it after fixing a password or a proxy.

{"logged_in": true, "account": {"id": "lab2", "status": "ready", "...": "..."}}

Status codes: 200 (read logged_in), 401, 404 (NOT_FOUND: no such account; or browser backend).

DELETE /admin/accounts/{id}

Removes the account from the pool and from the accounts file.

{"deleted": "lab2", "persisted": true}

persisted is false when the accounts file could not be written: the account is gone from the running service but still in the file. The default account cannot be deleted here, because it comes from ONCOKB_USERNAME; take it out of the environment, or disable it with POST /admin/accounts and {"username": "<its e-mail>", "enabled": false}.

Status codes: 200, 401, 404 (NOT_FOUND; or browser backend), 422 (INVALID_ACCOUNT: the default account).

GET /admin/usage

What was sent to oncokb.org, per UTC day and account.

{"days": 30, "requests": 13, "mb_total": 0.129,
 "rows": [{"day": "2026-11-10", "account": "default", "requests": 13, "errors": 0, "bytes_down": 125276, "bytes_up": 3525}]}

The rows count every request the service sent to oncokb.org: lookups, gene tables, the data version and gene list, logins, token checks, and the requests that failed. Bytes include the estimate for headers and handshakes, which is what a proxy billed per GB charges for.

Status codes: 200, 401, 404 (browser backend).

Error codes

A code appears in errors[].code. For a single call the HTTP status is the one in the heading. Inside a batch, a sample or a job, the call itself is 200 and each item carries its own status and errors.

An HTTP error raised without a code of its own gets HTTP_<status>, e.g. HTTP_400.

Codes marked "browser backend only" are never produced by the default wire backend.

HTTP 401

HTTP 404

HTTP 405

HTTP 409

HTTP 413

HTTP 422: your input (invalid)

HTTP 422: OncoKB's verdict (invalid)

HTTP 200: OncoKB has nothing (not_found)

HTTP 500

HTTP 503: oncokb.org could not be read (error)

Warnings

Warnings do not change status, but read them. Some have a detail after a colon.

Wire backend

Browser backend only

* The result was under-read. It is returned but not cached, so the next request loads the page again.

tumor_type_missing:pan_cancer_query, gene_hint_differs:A->B, unrecognised_biological_effect:TEXT and the two report warnings exist on both backends.

Limits

There is no per-client quota inside the service. Lookups beyond what the accounts can carry wait their turn, so one large job slows everyone's fresh single calls. A fresh lookup can wait up to 300 s for a free account before it is sent: set the client timeout above that (the Python example uses 330 s), or submit a job and poll.

Answers that nginx gives itself are HTML, not the JSON error body: 503 when a client exceeds the request rate, 413 for a request over 1,100 MB, 502 while the service restarts, 504 when an answer takes longer than 600 s, and 403 for an address outside the allow-list if the owner set one up.

oncokb.org answers an unknown gene with its whole evidence table (1.48 MB gzip). The service reads answers as a stream and drops such a download within the first 4 KB, by closing the connection it came on; each account keeps a second connection for lookups that may end this way. Genes OncoKB does not annotate are answered locally without a request.

Not supported: TSO500 or other vendors' TSV formats (send a VCF, or single variants), hg19 VCF upload, structural variants and copy number from a VCF (send single calls), HRD, LOH and mutational signatures, and PDFs on the wire backend.

Client examples

Python, standard library only

import json
import os
import time
import urllib.error
import urllib.request

B, K = os.environ["B"], os.environ["K"]


def call(method, path, body=None, timeout=330):
    """Returns (HTTP status, parsed JSON body, X-Request-ID)."""
    req = urllib.request.Request(B + path, method=method,
                                 data=json.dumps(body).encode() if body is not None else None,
                                 headers={"X-API-Key": K, "Content-Type": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=timeout) as r:
            return r.status, json.loads(r.read()), r.headers.get("X-Request-ID")
    except urllib.error.HTTPError as e:
        raw = e.read()
        try:
            out = json.loads(raw)
        except ValueError:            # nginx answered, not the service (e.g. during a restart)
            out = {"status": "error", "errors": [{"code": f"HTTP_{e.code}", "retryable": e.code in (502, 503, 504)}]}
        return e.code, out, e.headers.get("X-Request-ID")


def annotate(attempts=4, **body):
    """Returns the annotation; raises on input errors; retries only what the service says is retryable."""
    for attempt in range(attempts):
        code, out, rid = call("POST", "/api/v1/annotate", body)
        if code == 200:
            return out
        retryable = any(e.get("retryable") for e in out.get("errors", []))
        if code >= 500 and retryable and attempt < attempts - 1:
            time.sleep(5 * 4 ** attempt)          # 5 s, 20 s, 80 s
            continue
        raise RuntimeError(f"HTTP {code}, request {rid}: {out.get('errors')}")


a = annotate(gene="BRAF", alteration="V600E", tumor_type="MEL")
print(a["status"], a["oncogenicity"]["status"], a["evidence"]["highest_sensitive_level"])

# one sample
code, s, rid = call("POST", "/api/v1/sample", {
    "sample_id": "S-001", "tumor_type": "NSCLC", "options": {"detail": "summary"},
    "variants": [{"gene": "EGFR", "alteration": "L858R", "vaf": 0.31},
                 {"gene": "MET", "copy_number_type": "Amplification"},
                 {"gene": "EML4", "fusion_partner": "ALK"}],
    "biomarkers": {"tmb_high": True}})
for t in s["summary"]["therapies_in_tumor_type"]:
    print(t["level"], t["regimen"], "for", t["finding"])
for f in s["summary"]["not_read"]:
    print("not read:", f["finding"], f["errors"])

# a long list
code, job, rid = call("POST", "/api/v1/jobs", {"items": [
    {"gene": "IDH1", "alteration": "R132S", "tumor_type": "AML", "client_ref": "row-1"},
    {"gene": "ERBB2", "copy_number_type": "Amplification", "tumor_type": "BRCA", "client_ref": "row-2"}]})
while call("GET", job["poll"])[1]["status"] == "running":
    time.sleep(5)
results, offset = [], 0
while True:
    page = call("GET", f"{job['poll']}?offset={offset}&limit=500")[1]["results"]
    if not page:
        break
    results += page
    offset += len(page)
call("DELETE", job["poll"])

File upload, shell

J=$(curl -s -X POST $B/api/v1/vcf -H "X-API-Key: $K" -F "file=@sample.vcf.gz" -F mode=somatic -F tumor_type=NSCLC \
    | python3 -c 'import json,sys; print(json.load(sys.stdin)["job_id"])')
until curl -s $B/api/v1/jobs/$J -H "X-API-Key: $K" | grep -qE '"status": ?"(done|failed)"'; do sleep 10; done
curl -s $B/api/v1/jobs/$J/report.tsv -H "X-API-Key: $K" -o report.tsv
curl -s -X DELETE $B/api/v1/jobs/$J -H "X-API-Key: $K"

Checking the service before a run

curl -s -o /dev/null -w '%{http_code}\n' $B/ready      # 200: at least one account can carry requests
curl -s $B/api/v1/info -H "X-API-Key: $K"              # OncoKB data version in use

Browser backend

ONCOKB_BACKEND=browser runs the 3.x reader: one account, a Chromium tab per lookup. It is a fallback and is not installed on the deployed server. /ready, /health and provenance.backend say which backend answers. With the browser backend: