{"openapi":"3.1.0","info":{"title":"oncolabels API","version":"0.1.0","description":"EU-approved indications of targeted cancer therapies, from EMA product information (SmPC section 4.1). Read-only, no key. Data under CC BY 4.0; credit oncolabels and the European Medicines Agency.","license":{"name":"CC BY 4.0 (data)","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://oncolabels.com/api/v1"}],"paths":{"/indications":{"get":{"operationId":"search_indications","summary":"Search EU-approved indications by free text and filters","description":"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.","parameters":[{"name":"q","in":"query","schema":{"description":"Free text: tumour, biomarker, line, setting or medicine","type":"string","maxLength":300},"description":"Free text: tumour, biomarker, line, setting or medicine"},{"name":"tumour","in":"query","schema":{"description":"Tumour type, e.g. 'NSCLC', 'colorectal cancer', 'AML'","type":"string","maxLength":120},"description":"Tumour type, e.g. 'NSCLC', 'colorectal cancer', 'AML'"},{"name":"histology","in":"query","schema":{"description":"Histology within the tumour, e.g. 'squamous', 'adenocarcinoma', 'non-squamous', 'clear cell', 'medullary'","type":"string","maxLength":60},"description":"Histology within the tumour, e.g. 'squamous', 'adenocarcinoma', 'non-squamous', 'clear cell', 'medullary'"},{"name":"biomarker","in":"query","schema":{"description":"Biomarker, optionally with the alteration, e.g. 'EGFR', 'BRAF V600E', 'HER2-low', 'MSI-H'","type":"string","maxLength":120},"description":"Biomarker, optionally with the alteration, e.g. 'EGFR', 'BRAF V600E', 'HER2-low', 'MSI-H'"},{"name":"line","in":"query","schema":{"description":"Line of therapy: 1L, 2L or 3L+ (approvals without a line restriction are included)","type":"string","enum":["1L","2L","3L+"]},"description":"Line of therapy: 1L, 2L or 3L+ (approvals without a line restriction are included)"},{"name":"setting","in":"query","schema":{"description":"Treatment phase or disease stage","type":"string","enum":["neoadjuvant","adjuvant","perioperative","maintenance","induction","consolidation","early","locally-advanced","advanced","metastatic"]},"description":"Treatment phase or disease stage"},{"name":"medicine","in":"query","schema":{"description":"INN or brand","type":"string","maxLength":120},"description":"INN or brand"},{"name":"pd_l1_system","in":"query","schema":{"type":"string","enum":["TPS","CPS","TC","IC","TAP"]},"description":"The scoring system of a PD-L1 score to compare with the cut-offs"},{"name":"pd_l1_value","in":"query","schema":{"type":"number"},"description":"A PD-L1 score to compare with the cut-offs"},{"name":"detail","in":"query","schema":{"default":"concise","description":"full adds the label sentence, cut-off, scoring system and SmPC link","type":"string","enum":["concise","full"]},"description":"full adds the label sentence, cut-off, scoring system and SmPC link"},{"name":"limit","in":"query","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"understood":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"value":{"type":"string"},"from":{"type":"string"}},"required":["kind","value","from"],"additionalProperties":false},"description":"How the query was read"},"not_understood":{"type":"array","items":{"type":"string"},"description":"Words that matched nothing"},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_offset":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"hint":{"type":["string","null"]},"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable entry ID; pass it to get_indication for the label sentence"},"medicine":{"type":"string","description":"INN, with the EU brand names in brackets"},"tumour":{"type":"string"},"histology":{"description":"The histology the label limits the indication to within the tumour, e.g. 'Squamous cell carcinoma only'; null when any histology qualifies","type":["string","null"]},"setting":{"type":"string","description":"Line of therapy or treatment phase, and disease stage"},"requirement":{"type":"string","description":"The biomarker condition in the label, or 'no biomarker required'"},"biomarker_must_be_absent":{"type":"boolean","description":"The label requires the biomarker to be absent (EGFR/ALK-negative, RAS wild-type)"},"other_biomarkers":{"type":"array","items":{"type":"string"},"description":"Further biomarkers the label requires or excludes, e.g. 'HER2-positive' next to PD-L1 CPS ≥ 1; searches find the entry under these too"},"regimen":{"type":"string"},"conditions":{"description":"Histology, prior therapy, eligibility and follow-on treatment named in the label","type":["string","null"]},"conditional_approval":{"type":"boolean"},"needs_review":{"type":"boolean","description":"The label is ambiguous for this entry: check the SmPC"},"patient_score":{"description":"Only when the search gave a PD-L1 score","type":"string","enum":["meets the cut-off","scored differently"]},"link":{"type":"string","description":"The entry on oncolabels"},"tumour_as_labelled":{"description":"The tumour in the label's words; several when entries of one product read alike (detail: full)","type":"string"},"label_sentence":{"description":"The SmPC section 4.1 sentence (detail: full)","type":["string","null"]},"cut_off":{"type":["string","null"]},"scoring_system":{"type":["string","null"]},"age_group":{"type":"string"},"smpc":{"description":"Product information PDF (detail: full)","type":["string","null"]}},"required":["id","medicine","tumour","histology","setting","requirement","biomarker_must_be_absent","other_biomarkers","regimen","conditions","conditional_approval","needs_review","link"],"additionalProperties":false}},"dataset":{"type":"object","properties":{"version":{"type":"string"},"ema_data_of":{"type":"string","description":"Date of the EMA medicines data the dataset was built from"},"checked":{"type":"string","description":"Day oncolabels last found EMA's data still matching the dataset (checked every morning)"},"notice":{"type":"string"}},"required":["version","ema_data_of","checked","notice"],"additionalProperties":false}},"required":["understood","not_understood","total","offset","next_offset","hint","entries","dataset"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters"},"404":{"description":"Not found; the message says how to ask instead"}}}},"/indications/{id}":{"get":{"operationId":"get_indication","summary":"One indication with its label sentence","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","maxLength":40,"description":"Entry ID from search_indications or get_drug"},"description":"Entry ID from search_indications or get_drug"},{"name":"include_trace","in":"query","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","description":"Stable entry ID; pass it to get_indication for the label sentence"},"medicine":{"type":"string","description":"INN, with the EU brand names in brackets"},"tumour":{"type":"string"},"histology":{"description":"The histology the label limits the indication to within the tumour, e.g. 'Squamous cell carcinoma only'; null when any histology qualifies","type":["string","null"]},"setting":{"type":"string","description":"Line of therapy or treatment phase, and disease stage"},"requirement":{"type":"string","description":"The biomarker condition in the label, or 'no biomarker required'"},"biomarker_must_be_absent":{"type":"boolean","description":"The label requires the biomarker to be absent (EGFR/ALK-negative, RAS wild-type)"},"other_biomarkers":{"type":"array","items":{"type":"string"},"description":"Further biomarkers the label requires or excludes, e.g. 'HER2-positive' next to PD-L1 CPS ≥ 1; searches find the entry under these too"},"regimen":{"type":"string"},"conditions":{"description":"Histology, prior therapy, eligibility and follow-on treatment named in the label","type":["string","null"]},"conditional_approval":{"type":"boolean"},"needs_review":{"type":"boolean","description":"The label is ambiguous for this entry: check the SmPC"},"patient_score":{"description":"Only when the search gave a PD-L1 score","type":"string","enum":["meets the cut-off","scored differently"]},"link":{"type":"string","description":"The entry on oncolabels"},"tumour_as_labelled":{"description":"The tumour in the label's words; several when entries of one product read alike (detail: full)","type":"string"},"label_sentence":{"description":"The SmPC section 4.1 sentence (detail: full)","type":["string","null"]},"cut_off":{"type":["string","null"]},"scoring_system":{"type":["string","null"]},"age_group":{"type":"string"},"smpc":{"description":"Product information PDF (detail: full)","type":["string","null"]}},"required":["id","medicine","tumour","histology","setting","requirement","biomarker_must_be_absent","other_biomarkers","regimen","conditions","conditional_approval","needs_review","link"],"additionalProperties":false},"product":{"type":"object","properties":{"brand":{"type":"string"},"ema_product_number":{"type":["string","null"]},"smpc_en":{"type":["string","null"]},"label_updated":{"type":["string","null"]}},"required":["brand","ema_product_number","smpc_en","label_updated"],"additionalProperties":false},"trace":{"anyOf":[{"type":"object","properties":{"readers":{"type":"array","items":{"type":"string"}},"decisions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string"},"ambiguous":{"type":"boolean"}},"required":["field","value","reason","ambiguous"],"additionalProperties":false}}},"required":["readers","decisions"],"additionalProperties":false},{"type":"null"}]},"dataset":{"type":"object","properties":{"version":{"type":"string"},"ema_data_of":{"type":"string","description":"Date of the EMA medicines data the dataset was built from"},"checked":{"type":"string","description":"Day oncolabels last found EMA's data still matching the dataset (checked every morning)"},"notice":{"type":"string"}},"required":["version","ema_data_of","checked","notice"],"additionalProperties":false}},"required":["entry","product","trace","dataset"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters"},"404":{"description":"Not found; the message says how to ask instead"}}}},"/tests":{"get":{"operationId":"what_to_test","summary":"Biomarkers to test for a tumour","description":"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.","parameters":[{"name":"tumour","in":"query","required":true,"schema":{"type":"string","maxLength":120,"description":"Tumour type, e.g. 'metastatic colorectal cancer', 'NSCLC'"},"description":"Tumour type, e.g. 'metastatic colorectal cancer', 'NSCLC'"},{"name":"histology","in":"query","schema":{"description":"Histology within the tumour, e.g. 'squamous', 'adenocarcinoma'","type":"string","maxLength":60},"description":"Histology within the tumour, e.g. 'squamous', 'adenocarcinoma'"},{"name":"line","in":"query","schema":{"type":"string","enum":["1L","2L","3L+"]}},{"name":"setting","in":"query","schema":{"type":"string","enum":["neoadjuvant","adjuvant","perioperative","maintenance","induction","consolidation","early","locally-advanced","advanced","metastatic"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tumour":{"type":"string"},"groups":{"type":"array","items":{"type":"object","properties":{"how":{"type":"string","description":"Testing route"},"tests":{"type":"array","items":{"type":"object","properties":{"biomarker":{"type":"string"},"method":{"type":"string"},"result":{"type":"string","description":"What result the therapies need"},"cut_offs":{"type":"array","items":{"type":"string"}},"medicines":{"type":"array","items":{"type":"string"}},"only_tumour_agnostic":{"type":"boolean"}},"required":["biomarker","method","result","cut_offs","medicines","only_tumour_agnostic"],"additionalProperties":false}}},"required":["how","tests"],"additionalProperties":false}},"dataset":{"type":"object","properties":{"version":{"type":"string"},"ema_data_of":{"type":"string","description":"Date of the EMA medicines data the dataset was built from"},"checked":{"type":"string","description":"Day oncolabels last found EMA's data still matching the dataset (checked every morning)"},"notice":{"type":"string"}},"required":["version","ema_data_of","checked","notice"],"additionalProperties":false}},"required":["tumour","groups","dataset"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters"},"404":{"description":"Not found; the message says how to ask instead"}}}},"/medicines/{name}":{"get":{"operationId":"get_drug","summary":"A medicine's EU indications, target and links","description":"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.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","maxLength":120,"description":"INN or EU brand, e.g. 'osimertinib' or 'Tagrisso'"},"description":"INN or EU brand, e.g. 'osimertinib' or 'Tagrisso'"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"medicine":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"holder":{"type":["string","null"]},"atc":{"type":["string","null"]},"target":{"type":["string","null"]},"mechanism":{"type":["string","null"]},"authorised":{"type":"string"},"label_updated":{"type":["string","null"]},"conditional_approval":{"type":"boolean"},"orphan":{"type":"boolean"},"smpc_en":{"type":["string","null"]},"smpc_de":{"type":["string","null"]},"epar":{"type":["string","null"]},"biosimilars_and_generics":{"type":"array","items":{"type":"string"}}},"required":["brand","holder","atc","target","mechanism","authorised","label_updated","conditional_approval","orphan","smpc_en","smpc_de","epar","biosimilars_and_generics"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"indications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable entry ID; pass it to get_indication for the label sentence"},"medicine":{"type":"string","description":"INN, with the EU brand names in brackets"},"tumour":{"type":"string"},"histology":{"description":"The histology the label limits the indication to within the tumour, e.g. 'Squamous cell carcinoma only'; null when any histology qualifies","type":["string","null"]},"setting":{"type":"string","description":"Line of therapy or treatment phase, and disease stage"},"requirement":{"type":"string","description":"The biomarker condition in the label, or 'no biomarker required'"},"biomarker_must_be_absent":{"type":"boolean","description":"The label requires the biomarker to be absent (EGFR/ALK-negative, RAS wild-type)"},"other_biomarkers":{"type":"array","items":{"type":"string"},"description":"Further biomarkers the label requires or excludes, e.g. 'HER2-positive' next to PD-L1 CPS ≥ 1; searches find the entry under these too"},"regimen":{"type":"string"},"conditions":{"description":"Histology, prior therapy, eligibility and follow-on treatment named in the label","type":["string","null"]},"conditional_approval":{"type":"boolean"},"needs_review":{"type":"boolean","description":"The label is ambiguous for this entry: check the SmPC"},"patient_score":{"description":"Only when the search gave a PD-L1 score","type":"string","enum":["meets the cut-off","scored differently"]},"link":{"type":"string","description":"The entry on oncolabels"},"tumour_as_labelled":{"description":"The tumour in the label's words; several when entries of one product read alike (detail: full)","type":"string"},"label_sentence":{"description":"The SmPC section 4.1 sentence (detail: full)","type":["string","null"]},"cut_off":{"type":["string","null"]},"scoring_system":{"type":["string","null"]},"age_group":{"type":"string"},"smpc":{"description":"Product information PDF (detail: full)","type":["string","null"]}},"required":["id","medicine","tumour","histology","setting","requirement","biomarker_must_be_absent","other_biomarkers","regimen","conditions","conditional_approval","needs_review","link"],"additionalProperties":false}},"dataset":{"type":"object","properties":{"version":{"type":"string"},"ema_data_of":{"type":"string","description":"Date of the EMA medicines data the dataset was built from"},"checked":{"type":"string","description":"Day oncolabels last found EMA's data still matching the dataset (checked every morning)"},"notice":{"type":"string"}},"required":["version","ema_data_of","checked","notice"],"additionalProperties":false}},"required":["medicine","products","total","indications","dataset"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters"},"404":{"description":"Not found; the message says how to ask instead"}}}},"/changes":{"get":{"operationId":"whats_new","summary":"New approvals and label changes since a date","description":"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.","parameters":[{"name":"since","in":"query","schema":{"description":"YYYY-MM-DD","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"YYYY-MM-DD"},{"name":"limit","in":"query","schema":{"default":30,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"since":{"type":"string"},"new_medicines":{"type":"array","items":{"type":"object","properties":{"medicine":{"type":"string"},"brand":{"type":"string"},"authorised":{"type":"string"},"tumours":{"type":"array","items":{"type":"string"}}},"required":["medicine","brand","authorised","tumours"],"additionalProperties":false}},"label_updates":{"type":"array","items":{"type":"object","properties":{"medicine":{"type":"string"},"brand":{"type":"string"},"updated":{"type":"string"}},"required":["medicine","brand","updated"],"additionalProperties":false}},"entry_changes":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"medicine":{"type":"string"},"added":{"type":"array","items":{"type":"string"}},"changed":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}},"required":["date","medicine","added","changed","removed"],"additionalProperties":false}},"dataset":{"type":"object","properties":{"version":{"type":"string"},"ema_data_of":{"type":"string","description":"Date of the EMA medicines data the dataset was built from"},"checked":{"type":"string","description":"Day oncolabels last found EMA's data still matching the dataset (checked every morning)"},"notice":{"type":"string"}},"required":["version","ema_data_of","checked","notice"],"additionalProperties":false}},"required":["since","new_medicines","label_updates","entry_changes","dataset"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters"},"404":{"description":"Not found; the message says how to ask instead"}}}},"/values/{kind}":{"get":{"operationId":"list_values","summary":"Terms the search knows","description":"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.","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["tumours","histologies","biomarkers","medicines","lines","settings"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string"},"values":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"entries":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"note":{"type":["string","null"]}},"required":["value","label","entries","note"],"additionalProperties":false}}},"required":["kind","values"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters"},"404":{"description":"Not found; the message says how to ask instead"}}}}}}