API reference

Every endpoint of the oncolabels JSON API, with its parameters, an example and the fields it returns. The reference is generated from the API's own schemas, so it always matches what the API does.

Overview

Address
https://oncolabels.com/api/v1
Requests
GET only, with the parameters in the query string or the path.
Responses
JSON in UTF-8. Each answer names the dataset version and the date of its EMA data.
Limits
120 requests a minute from one network. Past that the API answers 429 for the rest of the minute.
Caching
An answer can be up to five minutes old.
Errors
400 lists the invalid parameters, 404 says how to ask instead, and 429 means too many requests.
Other sites
Open to requests from any website (CORS).
Description
OpenAPI 3.1.0, for code generators and custom GPT actions.
Licence
The data is under CC BY 4.0. Credit oncolabels and the European Medicines Agency, and say that the entries are generated by AI.

Search indications

GET/api/v1/indications

Find the EU-approved indications of targeted cancer therapies (EMA SmPC section 4.1) by tumour, biomarker, line of therapy, setting or medicine. `query` takes free text, read like the oncolabels search box ("NSCLC EGFR 2nd line", "HER2-low breast", "adjuvant melanoma"); the structured fields are added to it. Give a PD-L1 score to see which cut-offs it meets. A histology with a tumour keeps the approvals the label allows for it, and those for any histology. The result says how the query was read; if words were not understood, rephrase or look the term up with list_values. Approvals without a line restriction count in every line.

ParameterTypeDescription
qstringFree text: tumour, biomarker, line, setting or medicineup to 300 characters
tumourstringTumour type, e.g. 'NSCLC', 'colorectal cancer', 'AML'up to 120 characters
histologystringHistology within the tumour, e.g. 'squamous', 'adenocarcinoma', 'non-squamous', 'clear cell', 'medullary'up to 60 characters
biomarkerstringBiomarker, optionally with the alteration, e.g. 'EGFR', 'BRAF V600E', 'HER2-low', 'MSI-H'up to 120 characters
line1L | 2L | 3L+Line of therapy: 1L, 2L or 3L+ (approvals without a line restriction are included)
settingneoadjuvant | adjuvant | perioperative | maintenance | induction | consolidation | early | locally-advanced | advanced | metastaticTreatment phase or disease stage
medicinestringINN or brandup to 120 characters
pd_l1_systemTPS | CPS | TC | IC | TAPThe scoring system of a PD-L1 score to compare with the cut-offs
pd_l1_valuenumberA PD-L1 score to compare with the cut-offs
detailconcise | fullfull adds the label sentence, cut-off, scoring system and SmPC linkdefault concise
limitinteger1 to 100, default 25
offsetinteger0 to 9007199254740991, default 0

Example

curl "https://oncolabels.com/api/v1/indications?q=HER2%20gastric&limit=3"

See the response

Response fields
  • understood array of objectsHow the query was read
    • kind string
    • value string
    • from string
  • not_understood array of stringWords that matched nothing
  • total integer
  • offset integer
  • next_offset integer or null
  • hint string or null
  • entries array of objects
    • id stringStable entry ID; pass it to get_indication for the label sentence
    • medicine stringINN, with the EU brand names in brackets
    • tumour string
    • histology string or nullThe histology the label limits the indication to within the tumour, e.g. 'Squamous cell carcinoma only'; null when any histology qualifies
    • setting stringLine of therapy or treatment phase, and disease stage
    • requirement stringThe biomarker condition in the label, or 'no biomarker required'
    • biomarker_must_be_absent booleanThe label requires the biomarker to be absent (EGFR/ALK-negative, RAS wild-type)
    • other_biomarkers array of stringFurther biomarkers the label requires or excludes, e.g. 'HER2-positive' next to PD-L1 CPS ≥ 1; searches find the entry under these too
    • regimen string
    • conditions string or nullHistology, prior therapy, eligibility and follow-on treatment named in the label
    • conditional_approval boolean
    • needs_review booleanThe label is ambiguous for this entry: check the SmPC
    • patient_score meets the cut-off | scored differentlyOnly when the search gave a PD-L1 score
    • link stringThe entry on oncolabels
    • tumour_as_labelled stringThe tumour in the label's words; several when entries of one product read alike (detail: full)
    • label_sentence string or nullThe SmPC section 4.1 sentence (detail: full)
    • cut_off string or null
    • scoring_system string or null
    • age_group string
    • smpc string or nullProduct information PDF (detail: full)
  • dataset object
    • version string
    • ema_data_of stringDate of the EMA medicines data the dataset was built from
    • checked stringDay oncolabels last found EMA's data still matching the dataset (checked every morning)
    • notice string

One indication

GET/api/v1/indications/{id}

One entry in full: the SmPC section 4.1 sentence it was read from, every field, the product and its SmPC link. With include_trace, also how the entry was made: what each AI reader found and what the adjudicator decided where they disagreed, with its reasons.

ParameterTypeDescription
idrequiredin the pathstringEntry ID from search_indications or get_drugup to 40 characters
include_tracebooleandefault false

Example

curl "https://oncolabels.com/api/v1/indications/6772c64cec6d4d1e"

See the response

Response fields
  • entry object
    • id stringStable entry ID; pass it to get_indication for the label sentence
    • medicine stringINN, with the EU brand names in brackets
    • tumour string
    • histology string or nullThe histology the label limits the indication to within the tumour, e.g. 'Squamous cell carcinoma only'; null when any histology qualifies
    • setting stringLine of therapy or treatment phase, and disease stage
    • requirement stringThe biomarker condition in the label, or 'no biomarker required'
    • biomarker_must_be_absent booleanThe label requires the biomarker to be absent (EGFR/ALK-negative, RAS wild-type)
    • other_biomarkers array of stringFurther biomarkers the label requires or excludes, e.g. 'HER2-positive' next to PD-L1 CPS ≥ 1; searches find the entry under these too
    • regimen string
    • conditions string or nullHistology, prior therapy, eligibility and follow-on treatment named in the label
    • conditional_approval boolean
    • needs_review booleanThe label is ambiguous for this entry: check the SmPC
    • patient_score meets the cut-off | scored differentlyOnly when the search gave a PD-L1 score
    • link stringThe entry on oncolabels
    • tumour_as_labelled stringThe tumour in the label's words; several when entries of one product read alike (detail: full)
    • label_sentence string or nullThe SmPC section 4.1 sentence (detail: full)
    • cut_off string or null
    • scoring_system string or null
    • age_group string
    • smpc string or nullProduct information PDF (detail: full)
  • product object
    • brand string
    • ema_product_number string or null
    • smpc_en string or null
    • label_updated string or null
  • trace object or null
  • dataset object
    • version string
    • ema_data_of stringDate of the EMA medicines data the dataset was built from
    • checked stringDay oncolabels last found EMA's data still matching the dataset (checked every morning)
    • notice string

What to test

GET/api/v1/tests

List the biomarkers that decide eligibility for at least one EU-approved targeted therapy in a tumour (optionally a line or setting), grouped by how a pathology lab tests them, with the cut-offs and the medicines each result opens. Testing routes are curated from pathology practice, not from the labels.

ParameterTypeDescription
tumourrequiredstringTumour type, e.g. 'metastatic colorectal cancer', 'NSCLC'up to 120 characters
histologystringHistology within the tumour, e.g. 'squamous', 'adenocarcinoma'up to 60 characters
line1L | 2L | 3L+
settingneoadjuvant | adjuvant | perioperative | maintenance | induction | consolidation | early | locally-advanced | advanced | metastatic

Example

curl "https://oncolabels.com/api/v1/tests?tumour=colorectal%20cancer"

See the response

Response fields
  • tumour string
  • groups array of objects
    • how stringTesting route
    • tests array of objects
      • biomarker string
      • method string
      • result stringWhat result the therapies need
      • cut_offs array of string
      • medicines array of string
      • only_tumour_agnostic boolean
  • dataset object
    • version string
    • ema_data_of stringDate of the EMA medicines data the dataset was built from
    • checked stringDay oncolabels last found EMA's data still matching the dataset (checked every morning)
    • notice string

One drug

GET/api/v1/medicines/{name}

Everything oncolabels holds on one medicine: all EU-approved indications, target and mechanism of action (SmPC section 5.1), approval status, ATC code, biosimilars and generics, and links to the SmPC and EPAR.

ParameterTypeDescription
namerequiredin the pathstringINN or EU brand, e.g. 'osimertinib' or 'Tagrisso'up to 120 characters

Example

curl "https://oncolabels.com/api/v1/medicines/osimertinib"

See the response

Response fields
  • medicine string
  • products array of objects
    • brand string
    • holder string or null
    • atc string or null
    • target string or null
    • mechanism string or null
    • authorised string
    • label_updated string or null
    • conditional_approval boolean
    • orphan boolean
    • smpc_en string or null
    • smpc_de string or null
    • epar string or null
    • biosimilars_and_generics array of string
  • total integer
  • indications array of objects
    • id stringStable entry ID; pass it to get_indication for the label sentence
    • medicine stringINN, with the EU brand names in brackets
    • tumour string
    • histology string or nullThe histology the label limits the indication to within the tumour, e.g. 'Squamous cell carcinoma only'; null when any histology qualifies
    • setting stringLine of therapy or treatment phase, and disease stage
    • requirement stringThe biomarker condition in the label, or 'no biomarker required'
    • biomarker_must_be_absent booleanThe label requires the biomarker to be absent (EGFR/ALK-negative, RAS wild-type)
    • other_biomarkers array of stringFurther biomarkers the label requires or excludes, e.g. 'HER2-positive' next to PD-L1 CPS ≥ 1; searches find the entry under these too
    • regimen string
    • conditions string or nullHistology, prior therapy, eligibility and follow-on treatment named in the label
    • conditional_approval boolean
    • needs_review booleanThe label is ambiguous for this entry: check the SmPC
    • patient_score meets the cut-off | scored differentlyOnly when the search gave a PD-L1 score
    • link stringThe entry on oncolabels
    • tumour_as_labelled stringThe tumour in the label's words; several when entries of one product read alike (detail: full)
    • label_sentence string or nullThe SmPC section 4.1 sentence (detail: full)
    • cut_off string or null
    • scoring_system string or null
    • age_group string
    • smpc string or nullProduct information PDF (detail: full)
  • dataset object
    • version string
    • ema_data_of stringDate of the EMA medicines data the dataset was built from
    • checked stringDay oncolabels last found EMA's data still matching the dataset (checked every morning)
    • notice string

What's new

GET/api/v1/changes

Changes since a date: medicines newly authorised in the EU, product information updates, and what changed in oncolabels' entries (indications added, changed or removed). Defaults to the last 90 days.

ParameterTypeDescription
sincestringYYYY-MM-DDa date as YYYY-MM-DD
limitinteger1 to 100, default 30

Example

curl "https://oncolabels.com/api/v1/changes?since=2026-08-07"

See the response

Response fields
  • since string
  • new_medicines array of objects
    • medicine string
    • brand string
    • authorised string
    • tumours array of string
  • label_updates array of objects
    • medicine string
    • brand string
    • updated string
  • entry_changes array of objects
    • date string
    • medicine string
    • added array of string
    • changed array of string
    • removed array of string
  • dataset object
    • version string
    • ema_data_of stringDate of the EMA medicines data the dataset was built from
    • checked stringDay oncolabels last found EMA's data still matching the dataset (checked every morning)
    • notice string

Known terms

GET/api/v1/values/{kind}

The tumour types, histologies, biomarkers, medicines, lines of therapy or settings oncolabels knows, with how many entries each has. Use it when a search term is not understood.

ParameterTypeDescription
kindrequiredin the pathtumours | histologies | biomarkers | medicines | lines | settings

Example

curl "https://oncolabels.com/api/v1/values/biomarkers"

See the response

Response fields
  • kind string
  • values array of objects
    • value string
    • label string
    • entries integer or null
    • note string or null