{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "OnCo Open API", "version": "1.0.0", "summary": "The OnCo oncology knowledge graph as static files.", "description": "OnCo is a public, cited knowledge graph of oncology: 19,545 records in 20 kinds, one page per object, each with a plain-English TL;DR, a technical summary, dated facts and links to primary sources.\n\nEvery file here is written at build time and served from the CDN: no authentication, no rate limit beyond the CDN, permissive CORS. Files are regenerated on every deploy; meta.json carries the build time so clients can cache on it.\n\nField names and enums come from the Zod schema in src/lib/schema.ts in the repository. The Entity schema below points at /api/v1/schema.json, which is generated from that file, so the two cannot drift.\n\nKinds:\n- cancers (474): One page per disease: state of the art, history, and what is coming.\n- fronts (20): The fronts of the war on cancer: from imaging and early detection to ADCs, radiopharma, and cell therapy.\n- technologies (765): Every way we see, measure, or attack a tumour, explained.\n- targets (1674): The molecules drugs and tracers aim at.\n- drugs (1088): Approved and pipeline products, with what they hit and who makes them.\n- companies (1244): Who is building what.\n- institutions (726): The centres and universities that matter, mapped and ranked.\n- pathways (109): The classic signalling circuits, drawn and explained.\n- terms (1227): Glossary with plain-English TL;DRs and Wikipedia links.\n- trials (5969): Landmark and current trials that define the standard of care.\n- pairings (86): Things that work better together, and things that do not.\n- roadmaps (38): Where a technology has been and where it is heading.\n- ideas (1209): Hypotheses and new directions, linked to the evidence.\n- collections (139): The open databases and registries the field runs on.\n- people (1604): The clinicians and scientists doing the work: specialisms, bios, papers, and where to find them.\n- bottlenecks (54): The systemic constraints slowing the whole war on cancer, with the ideas that could break each one.\n- key papers (2582): The papers that changed practice or thinking, each explained: what it found, what it means, and what to be careful about.\n- journals (261): Where the evidence is published: the journals, their scope and access model, and the key papers each one carried.\n- biomarkers (102): The readouts a pathology report gives (PD-L1 CPS, HER2 IHC 3+, MSI-high), each under its gene or protein, with the thresholds approvals use and the tests that measure them.\n- years (174): One record per year: everything the corpus dates to it, each line linking to the record it was read from. The whole field on one chart is the timeline.\n\nLicence: code MIT; data CC BY-NC 4.0, free for individual and educational use with attribution (\"Data from OnCo (onco.cc)\" with a link to https://onco.cc); commercial use must contact OnCo to pay for the data. Nothing here is medical advice: facts may be incomplete or out of date, verify at the primary source each record links.\n\nDescription generated on 2026-10-03 from scripts/api-layout.ts.", "termsOfService": "https://onco.cc/about/#licence", "contact": { "name": "OnCo on GitHub", "url": "https://github.com/judegomila/OnCo/issues" }, "license": { "name": "CC BY-NC 4.0 (data); MIT (code)", "url": "https://creativecommons.org/licenses/by-nc/4.0/" } }, "externalDocs": { "description": "Endpoint list with live links, recipes and the MCP server", "url": "https://onco.cc/build/" }, "servers": [ { "url": "https://onco.cc", "description": "Production" } ], "tags": [ { "name": "corpus", "description": "The records, under /api/v1/" }, { "name": "feeds", "description": "Atom and iCalendar feeds for what changes" }, { "name": "site", "description": "Discovery files for crawlers and language models" } ], "paths": { "/api/v1/meta.json": { "get": { "operationId": "getMeta", "summary": "Build date, counts per kind, licence and the list of files", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meta" } } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This description", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/schema.json": { "get": { "operationId": "getSchema", "summary": "JSON Schema (draft 2020-12) of one entity, generated from the Zod schema that validates the corpus", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/schema+json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/all.json": { "get": { "operationId": "getAll", "summary": "Every entity plus a backlink map", "tags": [ "corpus" ], "description": "Several megabytes. Prefer the per-kind files unless you need the whole graph.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "entities", "incoming" ], "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "incoming": { "type": "object", "description": "For each id, the entities that link to it.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRef" } } } } } } } } } } }, "/api/v1/all.ndjson": { "get": { "operationId": "getAllNdjson", "summary": "Every entity, one JSON object per line, each with its site route", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } } } } }, "/api/v1/search.json": { "get": { "operationId": "getSearchDocs", "summary": "Compact search documents (id, kind, name, TL;DR, route)", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchDoc" } } } } } } } }, "/api/v1/similar.json": { "get": { "operationId": "getSimilar", "summary": "Up to eight similar records per id, with the links they share", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" }, "score": { "type": "number" }, "shared": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } } } } } } }, "/api/v1/embeddings.json": { "get": { "operationId": "getEmbeddings", "summary": "The concept-search index: ids, vocabulary and idf weights; the sparse unit vectors are in embeddings.bin", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/ask-index.json": { "get": { "operationId": "getAskIndex", "summary": "Names, aliases and curated question pairs used by Ask OnCo, the CLI and the MCP server", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/onco.nt": { "get": { "operationId": "getTriples", "summary": "The graph as RDF N-Triples using schema.org terms, with owl:sameAs links to Wikidata", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/n-triples": { "schema": { "type": "string" } } } } } } }, "/api/v1/rdf/{id}.ttl": { "get": { "operationId": "getEntityTurtle", "summary": "One entity as RDF Turtle: its own properties, its outgoing relations as the IRIs of the neighbours' pages, and owl:sameAs to Wikidata; the subject is the record's page URL", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "text/turtle": { "schema": { "type": "string" } } } }, "404": { "description": "No such id." } } } }, "/api/v1/ranking.json": { "get": { "operationId": "getRanking", "summary": "Institution ranking rows with the score components", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RankingRow" } } } } } } } }, "/api/v1/benchmark.json": { "get": { "operationId": "getBenchmark", "summary": "The open evaluation question set", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "/api/v1/{plural}.json": { "get": { "operationId": "listKind", "summary": "All entities of one kind", "tags": [ "corpus" ], "parameters": [ { "name": "plural", "in": "path", "required": true, "description": "The plural name of the kind, as used in the file name.", "schema": { "type": "string", "enum": [ "cancers", "fronts", "technologies", "targets", "drugs", "companies", "institutions", "pathways", "terms", "trials", "pairings", "roadmaps", "ideas", "collections", "people", "bottlenecks", "key papers", "journals", "biomarkers", "years" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } } } }, "/api/v1/{plural}.csv": { "get": { "operationId": "listKindCsv", "summary": "All entities of one kind as CSV: scalars as-is, arrays joined with '; ', nested records as JSON; the first line is a licence comment", "tags": [ "corpus" ], "parameters": [ { "name": "plural", "in": "path", "required": true, "description": "The plural name of the kind, as used in the file name.", "schema": { "type": "string", "enum": [ "cancers", "fronts", "technologies", "targets", "drugs", "companies", "institutions", "pathways", "terms", "trials", "pairings", "roadmaps", "ideas", "collections", "people", "bottlenecks", "key papers", "journals", "biomarkers", "years" ] } } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" } } } } } } }, "/api/v1/entities/{id}.json": { "get": { "operationId": "getEntity", "summary": "One entity with its site route and its neighbours grouped by kind", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case entity id, for example tnbc, trop2 or trastuzumab-deruxtecan.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponse" } } } }, "404": { "description": "No such id; the CDN returns the site's 404 page." } } } }, "/api/v1/for-me/{id}.json": { "get": { "operationId": "getForMeSituation", "summary": "One cancer's situation data for the For me page: standard-of-care rows with decision-page anchors, biomarkers resolved to target records, drugs with regional approval rows, recruiting trials, red cards and questions; assembled in the browser by src/lib/for-me-situation.ts", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id, for example tnbc or nsclc.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "No such cancer id." } } } }, "/api/v1/explore/{plural}.json": { "get": { "operationId": "listExploreRows", "summary": "Every row of one kind as the Explore page ranks it: id, name, TL;DR, route, status, evidence tier, link count, year, tags, and the per-cancer relevance signals the page scores from; the page carries the first 30 rows of each kind and fetches this file for the rest", "tags": [ "corpus" ], "parameters": [ { "name": "plural", "in": "path", "required": true, "description": "The plural name of the kind, as used in the file name; only the kinds Explore shows exist here.", "schema": { "type": "string", "enum": [ "drugs", "technologies", "targets", "trials", "pairings", "ideas", "companies", "institutions", "pathways", "terms", "roadmaps", "collections" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "name", "route", "rel" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" }, "name": { "type": "string" }, "tldr": { "type": "string" }, "route": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "degree": { "type": "integer" }, "evidence": { "type": "number" }, "year": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "string" }, "rel": { "type": "object", "description": "Per cancer id, which relevance signals apply (soc, pipeline, history, direct, indirect).", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "additionalProperties": true } } } } } } } }, "/api/v1/ideas/rankings/{view}.json": { "get": { "operationId": "listIdeaRankings", "summary": "Every idea one view of the Idea rankings page can order, in rank order: rank, score (null for the editorial Cherry picked list), the score parts the formula reads (GLOBOCAN burden with the sites it was read from, linked cancers, breadth, evidence counts, cost band, horizon, maturity) and, for Cherry picked, the one-sentence reason; the page carries the first 30 rows of each view and fetches this file for the rest. Most wanted is an empty list until a discussion thread has a thumbs-up", "tags": [ "corpus" ], "parameters": [ { "name": "view", "in": "path", "required": true, "description": "The view id, as used in the page's ?view= deep link.", "schema": { "type": "string", "enum": [ "bang-for-buck", "most-important", "hardest", "closest-to-reality", "cherry-picked", "most-wanted" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "rank", "parts", "score" ], "properties": { "rank": { "type": "integer" }, "score": { "type": [ "number", "null" ] }, "reason": { "type": "string" }, "parts": { "type": "object", "required": [ "id", "name", "tldr", "route", "cancers", "burden", "sites", "breadth", "evidence", "trials", "phase3", "drugs", "papers", "costRank", "maturity", "maturityRank" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tldr": { "type": "string" }, "route": { "type": "string" }, "cancers": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "route" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "route": { "type": "string" }, "site": { "type": "string" }, "viaParent": { "type": "string" } } } }, "burden": { "type": "integer", "description": "Annual new cases, world, both sexes, all ages, summed over the distinct GLOBOCAN sites of the linked cancers." }, "sites": { "type": "array", "items": { "type": "object", "required": [ "code", "label", "cases", "cancerIds" ], "properties": { "code": { "type": "integer" }, "label": { "type": "string" }, "cases": { "type": [ "integer", "null" ] }, "cancerIds": { "type": "array", "items": { "type": "string" } } } } }, "breadth": { "type": "integer" }, "evidence": { "type": "integer" }, "trials": { "type": "integer" }, "phase3": { "type": "integer" }, "drugs": { "type": "integer" }, "papers": { "type": "integer" }, "cost": { "type": "string", "enum": [ "small", "medium", "large" ] }, "costRank": { "type": "integer" }, "horizon": { "type": "number" }, "maturity": { "type": "string", "enum": [ "speculative", "preclinical-evidence", "early-clinical", "being-tested-at-scale" ] }, "maturityRank": { "type": "integer" } } } } } } } } } } } }, "/api/v1/tables/{table}.json": { "get": { "operationId": "listTableRows", "summary": "Every row of one paged table, as plain cells (strings, numbers, or objects with text, href, chip, sub and v; the kind browsers' rows carry id, name, tldr, route, status, facets and cols) in the table's default order; the page carries the first 30 rows (60 for a kind browser) and fetches this file for the rest. Tables: kind- for the kind browsers (kind-trials, kind-key-papers, kind-people, kind-companies, kind-drugs, kind-ideas, kind-institutions, kind-targets, kind-terms, kind-technologies, kind-cancers), evidence (trials by evidence score), china-trials, university-output, university-output-grouped, university-score, audit-findings-, audit-mismatches, audit-patches, audit-broken, audit-stale, pathway-matrix, pathway-nodes (one object per pathway with its nodes and products), dossier-trials-, genome-genes (every graded gene of /targets/genome/ with symbol, page, roles and evidence tier)", "tags": [ "corpus" ], "parameters": [ { "name": "table", "in": "path", "required": true, "description": "The table id, as listed in the summary.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "404": { "description": "No such table, or the table fits in one page and has no file." } } } }, "/api/v1/for-me/{id}.related.json": { "get": { "operationId": "getForMeRelated", "summary": "Everything in OnCo that touches one cancer, for the For me picker: state of the art, red cards, the pipeline, the hopeful records (failures, withdrawals and historic items left out) grouped by kind as id, name, TL;DR, route and status, and edgeIds, the sorted record ids the Edge 'For you' filter (/edge/?for=) matches feed items against: the cancer, its parent and subtypes, drugs approved or in phase 3 for it with those trials, its roadmaps and technologies", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id, for example tnbc or nsclc.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "stateOfArt", "redCards", "pipeline", "groups", "edgeIds" ], "properties": { "stateOfArt": { "type": "array", "items": { "type": "string" } }, "redCards": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pipeline": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "groups": { "type": "object", "additionalProperties": true }, "edgeIds": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "No such cancer id." } } } }, "/api/v1/pipeline/engine/{format}.json": { "get": { "operationId": "getEngineFormat", "summary": "The open drug engine for one format: format (id, name, axes, components), counts (cells per state including untried), coverage (medicines placed, partial, unresolved), rows and cols (the axis components), cells (a, b, state, drugs with their own state, counts, the other parts seen, evidence records with record id, field, kind, label, href and any quoted reason, and reasons), components (every value with its medicine count and states), drugs (each medicine with its components, the fields each was read from and a confidence, its state, evidence and reasons), unresolved (medicines the decomposer could not place, with what is missing), stopped (every recorded reason for stopping, in the record's words). States are derived from the named records only; untried means no medicine in the corpus combines the two parts", "tags": [ "corpus" ], "parameters": [ { "name": "format", "in": "path", "required": true, "description": "The format id, as in the page URL /pipeline/engine//.", "schema": { "type": "string", "enum": [ "adc", "radioligand", "car-t", "tcr-t", "bispecific", "degrader", "small-molecule", "antibody", "cytokine", "vaccine", "oncolytic-virus", "cell-therapy" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "format", "counts", "coverage", "rows", "cols", "cells", "components", "drugs", "unresolved", "stopped" ], "properties": { "format": { "type": "object", "additionalProperties": true }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "coverage": { "type": "object", "additionalProperties": { "type": "integer" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "cols": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "cells": { "type": "array", "items": { "type": "object", "required": [ "a", "b", "state", "drugs", "evidence" ], "properties": { "a": { "type": "object", "additionalProperties": true }, "b": { "type": "object", "additionalProperties": true }, "state": { "type": "string", "enum": [ "approved", "development", "stopped", "unclear" ] }, "drugs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "record", "kind", "state", "label", "href" ], "properties": { "record": { "type": "string" }, "field": { "type": "string" }, "kind": { "type": "string", "enum": [ "drug", "trial", "approval", "regional", "event", "registry" ] }, "state": { "type": "string" }, "label": { "type": "string" }, "href": { "type": "string" }, "quote": { "type": "string" } } } } }, "additionalProperties": true } }, "components": { "type": "object", "additionalProperties": true }, "drugs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "unresolved": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stopped": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "404": { "description": "No such format." } } } }, "/api/v1/pipeline/engine/index.json": { "get": { "operationId": "getEngineIndex", "summary": "The open drug engine's formats: id, name, page route, file, axes, cell counts per state (approved, development, stopped, unclear, untried) with medicine, partial and unresolved counts, and decomposer coverage; plus the drug records outside every format, by reason", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "formats", "drugs" ], "properties": { "drugs": { "type": "integer" }, "fetched": { "type": "string" }, "formats": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "outside": { "type": "array", "items": { "type": "object", "required": [ "reason", "count" ], "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } } } }, "/api/v1/tagged/{id}.json": { "get": { "operationId": "getTag", "summary": "One tag by its slug: slug, tag (canonical spelling), variants (every spelling sharing the slug), description, count, kinds (records per kind), related (tags sharing records, with the shared count) and records, every record carrying it as id, kind, name, route, status and tldr; the companion of /tagged/{slug}/", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The tag slug: lower case, hyphens between words, as in the /tagged/ URLs.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "tag", "variants", "description", "count", "kinds", "related", "records" ], "properties": { "slug": { "type": "string" }, "tag": { "type": "string" }, "variants": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "count": { "type": "integer" }, "kinds": { "type": "object", "additionalProperties": { "type": "integer" } }, "related": { "type": "array", "items": { "type": "object", "required": [ "slug", "tag", "shared" ], "properties": { "slug": { "type": "string" }, "tag": { "type": "string" }, "shared": { "type": "integer" } } } }, "records": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "name", "route" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" }, "name": { "type": "string" }, "route": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "tldr": { "type": "string" } } } } } } } } }, "404": { "description": "No record carries a tag with this slug." } } } }, "/api/v1/tagged/index.json": { "get": { "operationId": "listTags", "summary": "Every public tag as slug, tag (canonical spelling), variants, description, count and kinds (records per kind), most used first", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "slug", "tag", "count", "kinds" ], "properties": { "slug": { "type": "string" }, "tag": { "type": "string" }, "variants": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "count": { "type": "integer" }, "kinds": { "type": "object", "additionalProperties": { "type": "integer" } } } } } } } } } } }, "/api/v1/navigator/{id}.json": { "get": { "operationId": "getNavigatorCancer", "summary": "One cancer's data for the line-of-therapy navigator: its standard-of-care rows with resolved references, the products, technologies, trials, pairings, ideas and targets relevant to it with their biomarker fields, every caution pairing, caregiver details (toxicity, limitations, monitoring) for its products, and the questions to ask", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id, for example tnbc or nsclc.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "No such cancer id." } } } }, "/api/v1/explained/{id}.json": { "get": { "operationId": "getExplainedSection", "summary": "One cancer's section of Trials in plain words (or 'other'): rows, every trial whose full row is in this section as id, name, status, phase, year, tldr and nct in page order (the page carries the first 10 and fetches the rest); refs, the trials also studied in this cancer whose row is in an earlier section, as id, name and in (that section's key); trials, every trial with structured results as id, outcomes, setting and enrolment keyed by trial id, the records the page turns into sentences when a heading is opened", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id, for example tnbc or nsclc, or 'other'.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "rows", "refs", "trials" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "phase", "tldr" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "phase": { "type": "string" }, "year": { "type": "integer" }, "tldr": { "type": "string" }, "nct": { "type": "string" } } } }, "refs": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "in" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "in": { "type": "string" } } } }, "trials": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } } } } } }, "404": { "description": "No such cancer id, or no trials with results for it." } } } }, "/api/v1/roadmaps/{id}.json": { "get": { "operationId": "getRoadmapEras", "summary": "One roadmap's timeline in full: id, name, route; eras, every step in order with era (date range), title, status, description, refs (the linked records as id, kind, name, route, status, tldr), trials (those refs with structured outcomes, with setting and enrolment, as the plain-words explainer reads them) and papers (id, name, route, journal, year, whatItMeans); and watch, every item with expected date, source and resolved refs. The page keeps every era's heading and summary, opens the first and the current era, and fetches the other eras, the story cards and watch rows past the first 20 from here", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case roadmap id, for example tnbc-roadmap or ctdna-tests.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "route", "eras", "watch" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "route": { "type": "string" }, "eras": { "type": "array", "items": { "type": "object", "required": [ "era", "title", "status", "description", "refs", "trials", "papers" ], "additionalProperties": true } }, "watch": { "type": "array", "items": { "type": "object", "required": [ "item", "refs" ], "additionalProperties": true } } } } } } }, "404": { "description": "No such roadmap id." } } } }, "/api/v1/dossiers/{id}.json": { "get": { "operationId": "getDossier", "summary": "One target dossier as the page gathers it: id, name, symbol, route, asOf; xrefs (HGNC, Ensembl, UniProt, ChEMBL and the rest); products (id, name, status, modality, route); trials (id, name, nct, phase, status); pathways, companies and keyPapers as ids; hotspots (label, position, kind, frequency, drugs); openQuestions (id, question, stage, actor, source); assays (id, name, cutoff); resistance (drug class, mechanism, category); and the licence. The Export section of /dossiers/{id}/ links to this file rather than carrying it in the page", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case target id, for example pd1 or kras.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "route", "products", "trials" ], "additionalProperties": true } } } }, "404": { "description": "No such target id." } } } }, "/api/v1/cancers/{id}/uk.json": { "get": { "operationId": "getCancerUkPathway", "summary": "One cancer's UK and NHS layer: pathway steps with waiting-time standards, specialist centres (with institution ids), funding rows by line with NICE and SMC decisions and dates, Test Directory rows, UK trials with sites, figures with sources, support, four-nation differences, named gaps and every cited URL; the companion of /cancers/{id}/uk/", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id with a UK pathway, for example gallbladder.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "No UK pathway written for this cancer id." } } } }, "/api/v1/cancers/{id}/geography.json": { "get": { "operationId": "getCancerGeography", "summary": "One cancer's geography layer: GLOBOCAN 2022 country rates by sex with version and access date (rates.countries, rates.topTenIncidence, rates.topTenMortality), the high-burden regions with sources and resolved refs, programmes, spotlights, prevention evidence, figures, named gaps and every cited URL; the companion of /cancers/{id}/#geography", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id with a geography layer, for example gallbladder.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "No geography layer written for this cancer id." } } } }, "/api/v1/cancers/{id}/sections.json": { "get": { "operationId": "getCancerSections", "summary": "One cancer's section plan: the ten sections of the record in reading order, each with its purpose, placement (inline on the hub page or its own route), route, anchors, counts, the record fields and data patches it reads, and the sub-pages that belong to it; the companion of /cancers/{id}/ and /cancers/{id}/{section}/", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kebab-case cancer id, for example gallbladder or tnbc.", "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "route", "sections" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "route": { "type": "string" }, "asOf": { "type": "string" }, "thresholds": { "type": "object", "properties": { "inlineMaxKb": { "type": "integer" }, "inlineMaxRows": { "type": "integer" } } }, "sections": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "purpose", "placement", "href" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "purpose": { "type": "string" }, "placement": { "type": "string", "enum": [ "inline", "page" ] }, "route": { "type": [ "string", "null" ] }, "href": { "type": "string" }, "anchors": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "estimate": { "type": "object", "properties": { "rows": { "type": "integer" }, "kb": { "type": "integer" } } }, "fields": { "type": "array", "items": { "type": "string" } }, "patches": { "type": "array", "items": { "type": "string" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "route": { "type": "string" } } } } } } }, "machine": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "404": { "description": "Not a cancer id." } } } }, "/api/v1/navigator/lines.json": { "get": { "operationId": "getNavigatorLines", "summary": "Every product and technology as id, name, kind and the cancer ids it is relevant to: the navigator's 'already tried' chooser", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "kind", "cancers" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "drug", "technology" ] }, "cancers": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "/api/v1/my-cancers.json": { "get": { "operationId": "getMyCancers", "summary": "Every cancer as id, name, site route and hub group; the small chooser list the site's header chip, account menu and welcome step fetch on demand", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "route", "group" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "route": { "type": "string" }, "group": { "type": "string" } } } } } } } } } }, "/api/v1/kind-graph.json": { "get": { "operationId": "getKindGraph", "summary": "The home page's graph of kinds: nodes (kind, label, plural, count, route) and edges (a, b, links, href) with the total records, the total links and the counting rule; a link is an unordered pair of distinct records where either names the other in any relationship field, counted once, so the cancer-trial edge equals the sum over cancers of their distinct trials", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "rule", "total", "links", "nodes", "edges" ], "properties": { "rule": { "type": "string" }, "total": { "type": "integer" }, "links": { "type": "integer" }, "nodes": { "type": "array", "items": { "type": "object", "required": [ "kind", "label", "plural", "count", "route" ], "properties": { "kind": { "$ref": "#/components/schemas/Kind" }, "label": { "type": "string" }, "plural": { "type": "string" }, "count": { "type": "integer" }, "route": { "type": "string" } } } }, "edges": { "type": "array", "items": { "type": "object", "required": [ "a", "b", "links", "href" ], "properties": { "a": { "$ref": "#/components/schemas/Kind" }, "b": { "$ref": "#/components/schemas/Kind" }, "links": { "type": "integer" }, "href": { "type": "string" } } } } } } } } } } } }, "/api/v1/spotlight.json": { "get": { "operationId": "getSpotlight", "summary": "The home page spotlight: for every kind in the daily rotation, the most connected record as hero (id, name, route, TL;DR, three facts, up to eight connected records as pills, the connection count) plus two runners-up; with the selection rule, the schedule (day of year modulo the kinds list, reader's local date, ?spotlight= overrides) and buildKind, the set rendered into the home page HTML", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "rule", "schedule", "kinds", "buildKind", "sets" ], "properties": { "rule": { "type": "string" }, "schedule": { "type": "string" }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/Kind" } }, "buildKind": { "$ref": "#/components/schemas/Kind" }, "sets": { "type": "object", "additionalProperties": { "type": "object", "required": [ "kind", "label", "hero", "runnersUp" ], "properties": { "kind": { "$ref": "#/components/schemas/Kind" }, "label": { "type": "string" }, "hero": { "type": "object", "required": [ "id", "kind", "name", "route", "tldr", "facts", "pills", "connected" ], "additionalProperties": true }, "runnersUp": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "route" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "route": { "type": "string" } } } } } } } } } } } } } } }, "/api/v1/context/{id}.md": { "get": { "operationId": "getContext", "summary": "One entity as clean Markdown for language models: TL;DR, summary, fields, sources and connected records", "tags": [ "corpus" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "OK", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "No such id." } } } }, "/api/v1/context/index.md": { "get": { "operationId": "getContextIndex", "summary": "Index of every Markdown context file with the record's TL;DR", "tags": [ "corpus" ], "responses": { "200": { "description": "OK", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "summary": "llms.txt: what the site is, the licence and the best entry points, for language models", "tags": [ "site" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "operationId": "getLlmsFullTxt", "summary": "llms-full.txt: every record on one line with its TL;DR and the URL of its context file", "tags": [ "site" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/sitemap.xml": { "get": { "operationId": "getSitemap", "summary": "Sitemap of every page", "tags": [ "site" ], "responses": { "200": { "description": "OK", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/feeds/{feed}.xml": { "get": { "operationId": "getFeed", "summary": "Atom feeds: changelog, regulatory events, readout calendar, research pulse", "tags": [ "feeds" ], "parameters": [ { "name": "feed", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "changelog", "regulatory", "calendar", "pulse" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/edge/feed.xml": { "get": { "operationId": "getEdgeFeed", "summary": "Atom feed of Edge: the freshest papers, trial results, approvals, withdrawals, law, proposals and issues, ranked newest first; 500 items", "tags": [ "feeds" ], "responses": { "200": { "description": "OK", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/edge/feed.json": { "get": { "operationId": "getEdgeFeedJson", "summary": "JSON Feed 1.1 of Edge with an _onco extension per item (kind, date precision, venue, DOI, linked records); 500 items", "tags": [ "feeds" ], "responses": { "200": { "description": "OK", "content": { "application/feed+json": { "schema": { "type": "object" } } } } } } }, "/edge/{type}/feed.xml": { "get": { "operationId": "getEdgeTypeFeed", "summary": "Atom feed of one kind of Edge item only, the same ranking restricted to the kind; 100 items", "tags": [ "feeds" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "The kind's plural slug, as in the page's ?type= deep link.", "schema": { "type": "string", "enum": [ "approvals", "withdrawals", "results", "papers", "preprints", "law", "proposals", "weekly-issues" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/edge/{type}/feed.json": { "get": { "operationId": "getEdgeTypeFeedJson", "summary": "JSON Feed 1.1 of one kind of Edge item only, with the _onco extension; 100 items", "tags": [ "feeds" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "The kind's plural slug, as in the page's ?type= deep link.", "schema": { "type": "string", "enum": [ "approvals", "withdrawals", "results", "papers", "preprints", "law", "proposals", "weekly-issues" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/feed+json": { "schema": { "type": "object" } } } } } } }, "/newsletter/feed.xml": { "get": { "operationId": "getNewsletterFeed", "summary": "Atom feed of the weekly issue: what changed, regulatory events, upcoming readouts, what the journals said", "tags": [ "feeds" ], "responses": { "200": { "description": "OK", "content": { "application/atom+xml": { "schema": { "type": "string" } } } } } } }, "/catalysts/feed.ics": { "get": { "operationId": "getCatalystFeed", "summary": "iCalendar feed of regulatory decisions, expected readouts and congresses", "tags": [ "feeds" ], "responses": { "200": { "description": "OK", "content": { "text/calendar": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Kind": { "type": "string", "enum": [ "cancer", "section", "technology", "target", "drug", "company", "institution", "pathway", "term", "trial", "pairing", "roadmap", "idea", "collection", "person", "bottleneck", "paper", "journal", "biomarker", "year" ], "description": "cancer: cancers; section: fronts; technology: technologies; target: targets; drug: drugs; company: companies; institution: institutions; pathway: pathways; term: terms; trial: trials; pairing: pairings; roadmap: roadmaps; idea: ideas; collection: collections; person: people; bottleneck: bottlenecks; paper: key papers; journal: journals; biomarker: biomarkers; year: years" }, "Status": { "type": "string", "enum": [ "approved", "phase-3", "phase-2", "phase-1", "preclinical", "concept", "standard-of-care", "established", "emerging", "historic", "withdrawn", "active", "completed", "recruiting", "positive", "negative", "mixed", "planned" ] }, "EntityRef": { "type": "object", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" } } }, "NeighbourRef": { "type": "object", "required": [ "id", "kind", "name", "route" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" }, "name": { "type": "string" }, "route": { "type": "string", "description": "Site-relative URL of the entity page, for example /targets/trop2/." } } }, "Entity": { "$ref": "https://onco.cc/api/v1/schema.json", "description": "One record. The full schema (shared and kind-specific fields) is the generated JSON Schema at /api/v1/schema.json." }, "EntityResponse": { "type": "object", "required": [ "entity", "route", "neighbours" ], "properties": { "entity": { "$ref": "#/components/schemas/Entity" }, "route": { "type": "string" }, "neighbours": { "type": "object", "description": "Outgoing plus incoming neighbours, keyed by kind.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/NeighbourRef" } } } } }, "SearchDoc": { "type": "object", "required": [ "id", "kind", "name", "tldr", "route" ], "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" }, "name": { "type": "string" }, "tldr": { "type": "string" }, "route": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" } }, "additionalProperties": true }, "RankingRow": { "type": "object", "required": [ "rank", "id", "name", "score" ], "properties": { "rank": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2" }, "newsweekOncology2026": { "type": [ "integer", "null" ] }, "nci": { "type": [ "string", "null" ] }, "links": { "type": "integer" }, "newsweekPoints": { "type": "integer" }, "nciPoints": { "type": "integer" }, "linkPoints": { "type": "integer" }, "score": { "type": "integer" } } }, "Meta": { "type": "object", "required": [ "built", "schema", "counts", "total", "license", "attribution", "files" ], "properties": { "built": { "type": "string", "format": "date-time" }, "schema": { "type": "integer" }, "version": { "type": [ "string", "null" ] }, "attribution": { "type": "string", "examples": [ "Data from OnCo (https://onco.cc), CC BY-NC 4.0. Free for individual and educational use with attribution: name OnCo and link to https://onco.cc wherever the data or derived text appears. Commercial use must contact OnCo to pay for the data (https://onco.cc/about/#licence)." ] }, "licenseUrl": { "type": "string", "format": "uri" }, "license": { "type": "string", "examples": [ "CC BY-NC 4.0" ] }, "source": { "type": "string", "format": "uri" }, "total": { "type": "integer" }, "counts": { "type": "object", "properties": { "cancer": { "type": "integer" }, "section": { "type": "integer" }, "technology": { "type": "integer" }, "target": { "type": "integer" }, "drug": { "type": "integer" }, "company": { "type": "integer" }, "institution": { "type": "integer" }, "pathway": { "type": "integer" }, "term": { "type": "integer" }, "trial": { "type": "integer" }, "pairing": { "type": "integer" }, "roadmap": { "type": "integer" }, "idea": { "type": "integer" }, "collection": { "type": "integer" }, "person": { "type": "integer" }, "bottleneck": { "type": "integer" }, "paper": { "type": "integer" }, "journal": { "type": "integer" }, "biomarker": { "type": "integer" }, "year": { "type": "integer" } }, "additionalProperties": { "type": "integer" } }, "files": { "type": "array", "items": { "type": "object", "required": [ "path", "contents" ], "properties": { "path": { "type": "string" }, "contents": { "type": "string" } } } }, "feeds": { "type": "array", "items": { "type": "string" } }, "releases": { "type": "string", "format": "uri" }, "openapi": { "type": "string" } } } } } }