Public read-only HTTP API
Every page on this site reads from api.deliverome.org/surfaceome/v1/*, a Cloudflare Worker backed by a public D1 mirror of the project's annotation database. No authentication, CORS open to all origins, no rate limits.
Agent skill
A Markdown skill file documents the endpoints in the Anthropic skill format (name / description frontmatter plus instructions). Drop it into ~/.claude/skills/ and an agent can call the API without further prompting.
surfaceome-api
274 lines · 20.8 KB · Markdown
Use when the user asks whether a human gene is a cell-surface protein, asks for surface accessibility / drug targetability evidence on a specific gene, mentions SurfaceBench or the 147-gene triage benchmark, or compares LLM triage verdicts against public databases. Reads the public Surfaceome API at api.deliverome.org/surfaceome/v1/* — no auth, CORS open — to fetch deep-dive SurfaceomeRecords, per-source DB votes, and benchmark verdicts.
Download skill ↓Endpoints
SurfaceBench
147 curated proteins with ground-truth surface verdicts — the eval set behind the cost / accuracy figures.
GET
/v1/benchmark~51 KB147 ground-truth labels (gene, UniProt, class, verdict, signal, reason, rationale) for the current bench_version.
curl -s https://api.deliverome.org/surfaceome/v1/benchmark | jq '.count, .bench_version'GET
/v1/benchmark/export.tsv~7.6 MBLong-format TSV of the bench-restricted multi-model sweep: one row per (bench gene × model × variant) cell for the canonical bench_version. The verdict is the cell's majority over its 3 replicates, as in the paper, with n_reps, majority_agreement, is_match and replicate-summed *_total telemetry. Adds the 5-DB vote vector and truth_verdict / truth_signal / truth_reason to the triage export shape.
curl -s https://api.deliverome.org/surfaceome/v1/benchmark/export.tsv | head -3GET
/v1/benchmark/{SYMBOL}~358 BSingle gene's ground-truth label and rationale for the latest bench_version.
curl -s https://api.deliverome.org/surfaceome/v1/benchmark/ERBB2 | jq '.truth_verdict, .truth_reason'GET
/v1/benchmark/matrix~7.5 MBFull SurfaceBench matrix in one round-trip: per-gene truth label, 5-DB vote vector, and per-(model, variant) verdicts with the agent's free-text reasoning on each cell. `models` lists the eight benchmarked Claude models (Haiku 4.5 / 5.5, Sonnet 4.6 / 5 / 5.5, Opus 4.8 / 5 / 5.5) and `variants` the prompt variants (naive, ncbi, ncbi_effort_low — the ncbi prompt at low reasoning effort — web_ncbi, pubmed_ncbi); not every model ran every variant, and a missing (model, variant) is null. Each cell is the majority over its 3 replicates (refused replicates excluded) — the same per-cell numbers as the paper — with `n_reps`, `majority_agreement` and replicate-summed `totals`; `reasoning` and per-call telemetry come from the representative `replicate`. A cell whose replicates were all declined by the model's safety classifier has `verdict: null` and `error: "refusal"`. Drives the SurfaceBench page's side-drawer.
curl -s https://api.deliverome.org/surfaceome/v1/benchmark/matrix | jq '.n_genes, .models, .variants, .headline_variant'
Genome-wide
All ~19,300 protein-coding human genes with their 5-DB surface-vote vector plus the per-model triage matrix (Sonnet across the full genome; Haiku + Opus on the 147 SurfaceBench genes).
GET
/v1/catalog~4.2 MBPer-gene-per-source surface-vote matrix (5 gating DBs: UniProt / GO / SURFY / CSPA / HPA) plus a per-model triage matrix (Haiku / Sonnet / Opus × verdict + short reason code; Sonnet applies a pubmed_ncbi rescue when its ncbi call is a false-negative), a deep_dive flag, an optional `intern` internalization grade (the sequence-prior SeqGrade — see the Internalization section; full record on GET /v1/internalization/{SYMBOL}), and — for deep-dived rows — an optional `ddf` projection with the catalog-filterable subset of Filters (surface_accessibility, confidence, evidence_grade, n_papers_selected_band, surface_call_reason, ...). One row per protein-coding gene (~19k). Free-text reasoning per run is on GET /v1/triage/{SYMBOL}; the full deep-dive SurfaceomeRecord is on GET /v1/genes/{SYMBOL}. Top-level `n_papers_selected_cutoffs` reports the cohort percentile thresholds (p10, p90) used to compute `ddf.n_papers_selected_band` on each row. Server-side `json_extract` slims the deep-dive read (~4 KB/row on the wire out of ~120 KB per record).
curl -s https://api.deliverome.org/surfaceome/v1/catalog | jq '.universe_version, .n_rows, .n_with_triage, .n_papers_selected_cutoffs'GET
/v1/triage/{SYMBOL}~2.7 KBEvery triage run on file for one gene — model × prompt-variant × replicate — with verdict, reason code, confidence, latency, per-call token counts, and the agent's free-text verdict_reasoning paragraph.
curl -s https://api.deliverome.org/surfaceome/v1/triage/ERBB2 | jq '.count, .runs[0]'GET
/v1/triage/{SYMBOL}/{model}/{variant}Per-cell replicate detail for one (gene, model, prompt_variant) cell — any benchmarked model id (e.g. claude-opus-5-5) and variant (naive, ncbi, ncbi_effort_low, web_ncbi, pubmed_ncbi). Returns every replicate's verdict + verdict_reasoning + per-call token usage + latency, plus the agent's overall majority verdict computed across replicates. A replicate the model's safety classifier declined has a null verdict and `error: "refusal"`, and is excluded from the majority.
curl -s https://api.deliverome.org/surfaceome/v1/triage/ERBB2/claude-sonnet-4-6/ncbi | jq '.majority_verdict, .replicates | length'GET
/v1/triage/export.tsv~1014 KBLong-format TSV of every triage run for one run_id. Each row is (gene × model × variant × replicate) with the 5-DB votes and uniprot_acc joined in server-side. Default run_id is mainbench_canonical_v2 (the bench sweep); pass run_id=genome_full_sonnet_ncbi_v2 for the full ~19k-gene Sonnet sweep. Reasoning columns are omitted by default to keep figure-input exports prose-free — add with_reasoning=1 for the full export below.
curl -s 'https://api.deliverome.org/surfaceome/v1/triage/export.tsv?run_id=genome_full_sonnet_ncbi_v2&replicate=1' | head -3GET
/v1/triage/export.tsv?run_id=genome_full_sonnet_ncbi_v2&with_reasoning=1~21 MBFull genome-wide triage export WITH agent reasoning: the ~19k-gene Sonnet/NCBI sweep with predicted_key_uncertainty and the agent's free-text verdict_reasoning paragraph appended as the trailing columns. with_reasoning=1 works on any run_id; this is the bulk counterpart to the per-gene /v1/triage/{SYMBOL} reasoning.
curl -s 'https://api.deliverome.org/surfaceome/v1/triage/export.tsv?run_id=genome_full_sonnet_ncbi_v2&replicate=1&with_reasoning=1' | head -3
Deep dive
Per-gene deep-dive SurfaceomeRecords, plus the broad genome-wide ortholog lookup and a liveness check.
GET
/v1/health32 BLiveness check. Returns the count of deep-dive SurfaceomeRecords on file.
curl -s https://api.deliverome.org/surfaceome/v1/healthGET
/v1/genes~861 KBIndex of genes with a deep-dive SurfaceomeRecord on file. Summary fields only: gene_symbol, uniprot_acc, schema_version, triage_signal, surface_status, annotated_at.
curl -s https://api.deliverome.org/surfaceome/v1/genes | jq '.count'GET
/v1/genes/{SYMBOL}~114 KBSurfaceomeRecord JSON for one gene: the executive summary, evidence-grade rationale, per-method observations, deterministic features, and accessibility risks. The citation ledger (verbatim quotes + provenance) is NO LONGER inlined here — it moved to GET /v1/genes/{SYMBOL}/evidence, trimming this record ~45%. The narrative reasoning stays inline; only the ledger split out.
curl -s https://api.deliverome.org/surfaceome/v1/genes/ERBB2 | jq '.executive_summary.surface_accessibility, .confidence'GET
/v1/genes/{SYMBOL}/evidenceThe evidence ledger for one gene: { gene, evidence: [...] }, where each entry carries the verbatim quote, its source provenance (PMC / PMID / DOI / URL), evidence tier, and the cross-planner duplicate links. Split out of GET /v1/genes/{SYMBOL} (it was 42–47% of that payload) so consumers that only need the record's reasoning don't pay for the citations; fetch this to resolve the evidence_id chips back to their sources.
curl -s https://api.deliverome.org/surfaceome/v1/genes/ERBB2/evidence | jq '.evidence | length'GET
/v1/orthologs/{SYMBOL}~401 BMouse and cynomolgus orthologs for any human gene from the latest Ensembl Compara release (broad genome-wide raw Compara — full-length % identity + orthology type, ~5k genes). The per-gene record's deterministic_features.orthologs is the deeper view: mouse/cyno canonical, ECD % identity + projected topology + sequence, for deep-dived genes only.
curl -s https://api.deliverome.org/surfaceome/v1/orthologs/ERBB2 | jq '.release_version, (.orthologs | length)'
Internalization
A standalone pass (separate from the deep dive): how readily a protein is taken from the cell surface into the cell, graded blind by a frontier model from amino-acid sequence + extracellular/cytoplasmic topology alone. The one-word grade per gene rides on each /v1/catalog row as `intern`; this endpoint returns the full record.
GET
/v1/internalization/{SYMBOL}Full InternalizationRecord for one gene from the opus-5 sequence-prior sweep: the model-prior track's overall 5-point SeqGrade (very_high / high / moderate / low / very_low / unknown) with per-isoform grade, DeepTMHMM E/C topology, endocytic sorting motifs, and the model's reasoning — scoped to intrinsic / basal endocytic propensity (not antibody- or ADC-induced uptake). Returns null for a gene not in the internalization cohort.
curl -s https://api.deliverome.org/surfaceome/v1/internalization/LRP1 | jq '.model_priors[0].overall_grade, .model_priors[0].per_isoform[0].grade'
History
Record history + numbered data releases. Every distinct state the API served for a gene (record, evidence ledger, Markdown export) is archived write-once, with one revision per actual change — numbering starts at 1 for a gene's first archived version; there's no revision 0. Revision and release bodies never change; cite them by URL, or by the release's Zenodo version DOI. Release 1.0.0, the 2026-08-15 Zenodo deposit, predates this system and is Zenodo-only: it has no per-gene member records here (see the DOI in its /v1/releases/1.0.0 response instead).
GET
/v1/genes/{SYMBOL}/revisionsEvery archived revision of this gene's served record (newest first), each with a `changed` label ("first_archived", or the parts — record/evidence/markdown — that differ from the previous revision) and the releases it belongs to.
curl -s https://api.deliverome.org/surfaceome/v1/genes/ERBB2/revisions | jq '.current_revision, .revisions[0].changed, .revisions[0]'GET
/v1/genes/{SYMBOL}/revisions/{n}Revision n of the record, byte-for-byte as served; also /evidence and .md.
curl -s https://api.deliverome.org/surfaceome/v1/genes/ERBB2/revisions/1 | jq '.gene.hgnc_symbol'GET
/v1/releasesNumbered data releases with their GitHub tag and Zenodo version DOI, and `api_members` (false only for 1.0.0, the pre-history Zenodo deposit).
curl -s https://api.deliverome.org/surfaceome/v1/releases | jq '.releases'GET
/v1/releases/{version}One release: metadata + the revision of every gene in it. Release 1.0.0 returns members: [] and an `api_note` pointing at its Zenodo DOI instead — its records were never served through the API.
curl -s https://api.deliverome.org/surfaceome/v1/releases/1.0.0 | jq '.n_genes, .zenodo_version_doi, .api_members, .api_note'GET
/v1/releases/{version}/genes/{SYMBOL}A gene as it was in that release; also /evidence and .md. 404s `release_not_in_api_history` (with the Zenodo DOI) for release 1.0.0, whose records live only in the Zenodo deposit.
curl -s https://api.deliverome.org/surfaceome/v1/releases/1.0.0/genes/ERBB2 | jq '.error, .zenodo_version_doi'
Contact sites
Versioned mapped ligand and antibody contacts from public D1. Coverage is an audit snapshot, not an exhaustive ligand census. Coordinates use canonical UniProt numbering.
GET
/v1/contact-sites/releases/currentCurrent release, source provenance, coverage and excluded identifiers.
curl -s https://api.deliverome.org/surfaceome/v1/contact-sites/releases/currentGET
/v1/contact-sites/releases/{release}/proteins/{uniprot}Ligand identities, category metadata and one observed footprint per named ligand. scope=extracellular by default; scope=all includes other compartments. Audited empty results differ from not_audited.
curl -s 'https://api.deliverome.org/surfaceome/v1/contact-sites/releases/RELEASE_ID/proteins/P00533'GET
/v1/contact-sites/releases/{release}/proteins/{uniprot}/ligands/{ligandId}/evidenceUp to 100 original observations per page; pass next_cursor as cursor. Keep the same release and scope on every request. Omit ligands/{ligandId}/ to retrieve all observations, including unnamed partners.
curl -s 'https://api.deliverome.org/surfaceome/v1/contact-sites/releases/RELEASE_ID/proteins/P00533/evidence?scope=all'
Reproducibility
Reproducibility replicates — NOT published records. For the run-to-run reproducibility analysis (Supplementary Figure 16), 50 deep-dive genes drawn at random were re-analysed; each is held three ways: the published record as served when the study ran (published_snapshot), a full from-scratch re-run with the same prompts (full_rerun), and a fixed-evidence replay that re-ran only the section builders and synthesizer on the published evidence (fixed_evidence_replay). Every response carries reproducibility_replicate: true and a link back to the published record, which stays at /v1/genes/{SYMBOL}. The same records are deposited on Zenodo.
GET
/v1/replicatesEvery replicate study with its kinds and genes (metadata only).
curl -s https://api.deliverome.org/surfaceome/v1/replicates | jq '.studies[] | {study_id, n_genes, kinds: (.kinds | keys)}'GET
/v1/genes/{SYMBOL}/replicatesThe replicates held for one gene, with a link to each; 404 if the gene was not sampled.
curl -s https://api.deliverome.org/surfaceome/v1/genes/M6PR/replicates | jq '.replicates[] | {replicate_kind, url}'GET
/v1/genes/{SYMBOL}/replicates/{study}/{kind}One replicate SurfaceomeRecord in full (evidence included) under .record, wrapped with its study, kind, run ids and the deep-dive tier computed by the same rule as the published record. kind is published_snapshot, full_rerun or fixed_evidence_replay.
curl -s https://api.deliverome.org/surfaceome/v1/genes/M6PR/replicates/deep_dive_concordance_v1/full_rerun | jq '.reproducibility_replicate, .deep_dive_tier, .record.filters.surface_accessibility'
Discovery & utility
Self-describing entry points for agents and tooling. Start at /v1 to walk the whole surface without scraping this page; the site root also serves an llms.txt that points here.
GET
/v1Self-describing index: the full endpoint catalogue with path templates, links to these docs / the downloadable skill / llms.txt / the SurfaceomeRecord schema, and the live dataset versions (bench_version, universe_version, n_annotations). Also served at the bare service root. Hit this first to discover the API.
curl -s https://api.deliverome.org/surfaceome/v1 | jq '.endpoints[].path, .versions'GET
/v1/meta/sizesApproximate response size for every endpoint, computed live from D1 row counts + LENGTH(...) sums — budget a fetch before making it. Drives the ~size badges on this page.
curl -s https://api.deliverome.org/surfaceome/v1/meta/sizes | jq '.endpoints'
Catalog presets
Pure predicates over a record's filters block (the shortlist the toolbar at / uses). Source of truth lives at viewer/lib/catalog-presets.ts; the same predicates back the deep-dive-preset-membership.tsv export in the Zenodo deposit so a reanalyst can verify membership without re-implementing the rule.
- Canonical
The high-confidence surface shortlist: a confident overall call — surface-dominant or mixed, accessible, dense evidence (at least supportive-but-indirect; weak and conflicting excluded). Full gate on the API page.
surface_call_reason ∉ {tissue_restricted_surface, lysosomal_exocytosis} AND grade ∈ {direct_multi_method, direct_single_method, supportive_but_indirect} AND confidence ∈ {high, moderate} AND surface_specificity ∈ {surface_dominant, mixed} AND (state_dependence ∈ {low, moderate, unclear} OR expression_level ∈ {moderate, high}) AND surface_accessibility ∈ {high, moderate} AND evidence_density ∈ {high, moderate}- Likely
Broader surface set than Canonical — meets the same surface-accessibility bar but falls short on other criteria: admits predominantly intracellular proteins with a surface fraction (e.g. SRC via lysosomal exocytosis, HMGB1 via DAMP release) and stronger state-dependence. This chip excludes Canonical genes; every Canonical gene is also Likely, so select both chips to see the full Likely tier.
passesLikely(f) AND NOT passesCanonical(f) // chip = the likely-ONLY band passesLikely(f) := ( grade ∈ {direct_multi_method, direct_single_method, supportive_but_indirect} OR ( grade == weak // structural-surface carve-out AND surface_call_reason ∈ {classical_surface_receptor, multipass_with_exposed_loops, gpi_anchored, tissue_restricted_surface} ) ) AND surface_specificity ∈ {surface_dominant, mixed, mostly_intracellular} AND surface_accessibility ∈ {high, moderate} // low → below-Likely 'low' tier AND state_dependence ∈ {low, moderate, high, unclear, null}- Cell-state induced
Subset of Likely that reaches the surface because of a cell-state change — activation, stress, or oncogenic transformation — rather than constitutively (SRC, CD63, HMGB1, C3). Defined by the deep dive's surface-mechanism call (genuine state-induced surfacing), not by mere tumour association; the oncogenic / immune / stress / infection trigger is shown as the sub-chips.
passesLikely(f) AND state_dependence ∈ {moderate, high, unclear, null} AND surface_call_reason ∈ {cell_state_induced, lysosomal_exocytosis}- Cell-type restricted
Subset of Likely with constitutive surface in specific cell types only (KLK2 in prostate, etc.). Different cell types — not same cell across states.
passesLikely(f) AND state_dependence ∈ {moderate, high} AND surface_call_reason == tissue_restricted_surface- Cancer
induction_trigger = oncogenic — surface form is induced by oncogenic transformation specifically (TROP2-class cancer overexpression, eSrc-class lysosomal-exocytosis pool). Split off from Disease because oncogenic is the largest single trigger in the cohort and conflating it with infection / cell-death buries those rarer buckets.
- Other disease
induction_trigger ∈ {cell_death, infection} — non-oncogenic disease state (pyroptosis / necroptosis / immune-cell-death; viral or bacterial infection). HMGB1-class DAMP release lives here rather than under Cancer.
- Stress
induction_trigger = stress_hypoxia — surface form responds to hypoxia / ER stress / metabolic stress. Independent of tumor / inflammation context.
- Immune
induction_trigger = immune — surface form responds to immune activation. Coarse umbrella for both constitutive-surface-with-immune-modulation (KIR2DL1-class) and release-by-immune-activation (HMGB1 DAMP-release pool); the prose distinguishes.
When “Cell-state induced” is active, the catalog reveals sub-axes by induction_trigger: