Skip to main content
The Deliverome ProjectSurfaceomev1.3.0

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 and CORS open to all origins; generous per-IP rate limits apply (see Rate limits below).

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

318 lines · 30.2 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 KB

    147 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 MB

    Long-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 -3

  • GET/v1/benchmark/{SYMBOL}~358 B

    Single gene's ground-truth label and rationale for the latest bench_version.

    curl -s https://api.deliverome.org/surfaceome/v1/benchmark/CD19 | jq '.truth_verdict, .truth_reason'

  • GET/v1/benchmark/matrix~7.5 MB

    Full 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,324 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 MB

    Per-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, 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 (19,324), returned in a single response — there is no pagination (≈14 MB uncompressed, ≈0.5 MB gzipped on the wire); use GET /v1/catalog/{SYMBOL} for one gene. Top-level `row_schema` versions the row shape; `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 to ~1.5 KB per deep-dived row (out of ~120 KB per record). Free-text reasoning per run is on GET /v1/triage/{SYMBOL}; the full deep-dive SurfaceomeRecord is on GET /v1/genes/{SYMBOL}. row_schema 11 adds an optional top-level libtopo: how many of the gene's library members have a DeepTMHMM topology for their exact designed sequence (present only when at least one does).

    curl -s https://api.deliverome.org/surfaceome/v1/catalog | jq '.universe_version, .row_schema, .n_rows, .n_with_triage, .n_papers_selected_cutoffs'

  • GET/v1/catalog/{SYMBOL}

    One gene's slim catalog row: symbol, UniProt accession, the 5-DB vote vector and its count (n_sources), the deep_dive flag and the number of SURFACE-Bind sites. Backs the DB-presence strip on each gene page. 404 `gene_not_in_universe` for a symbol outside the protein-coding cohort.

    curl -s https://api.deliverome.org/surfaceome/v1/catalog/ERBB2 | jq '.n_sources, .db, .deep_dive'

  • GET/v1/triage/{SYMBOL}~2.7 KB

    Every 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 a `majority` object (verdict, reason, reasoning, confidence, n_reps, agreement) computed across replicates. A replicate the model's safety classifier declined has a null verdict and `error: "refusal"`, and is excluded from the majority. Serves the 147 SurfaceBench genes only (it reads the canonical benchmark sweep): any other gene returns `replicates: []` and `majority: null` — use GET /v1/triage/{SYMBOL} for genome-wide runs.

    curl -s https://api.deliverome.org/surfaceome/v1/triage/CD19/claude-sonnet-4-6/ncbi | jq '.majority.verdict, (.replicates | length)'

  • GET/v1/triage/export.tsv~1014 KB

    Long-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 19,324-gene Sonnet sweep (the NCBI-context pass). The PubMed-context rescue pass — one pass, 14,404 rows re-triaging the genes the NCBI pass called no — is recorded under four run_ids, one per batch: genome_full_sonnet_pubmed_ncbi_v1, genome_intracellular_pubmed_ncbi_v1, genome_1db_trim_pubmed_ncbi_v1 and genome_optcut_zerodb_pubmed_ncbi_v1. The Zenodo deposit's triage-runs-genome-with-reasoning.tsv combines both passes with a triage_pass column. 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 -3

  • GET/v1/triage/export.tsv?run_id=genome_full_sonnet_ncbi_v2&with_reasoning=1~21 MB

    Full genome-wide triage export WITH agent reasoning: the 19,324-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 (JSON, evidence ledger and Markdown brief), plus the broad genome-wide ortholog lookup, the internalization and tag-site annotations, and a liveness check.

  • GET/v1/health32 B

    Liveness check: { ok, n_annotations, cache_epoch } — n_annotations is the count of deep-dive SurfaceomeRecords on file. Never rate-limited, so uptime probes always succeed.

    curl -s https://api.deliverome.org/surfaceome/v1/health

  • GET/v1/genes~861 KB

    Index of genes with a deep-dive SurfaceomeRecord on file. Summary fields only: gene_symbol, uniprot_acc, schema_version, prompt_corpus_version, cohort_run_id, confidence, triage_signal, surface_status, annotated_at.

    curl -s https://api.deliverome.org/surfaceome/v1/genes | jq '.count'

  • GET/v1/genes/{SYMBOL}~114 KB

    SurfaceomeRecord 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. The served record is the stored deep-dive record plus fields the Worker fills from other public tables on each request: deep_dive_tier and deep_dive_facet, the first-pass triage_signal / triage_reasoning (the NCBI-context call; a rescued gene's PubMed-pass call is in /v1/triage/{SYMBOL}), gene.ensembl_canonical_protein, DeepTMHMM's own call on canonical_topology, refreshed isoform / paralog / ortholog / SURFACE-Bind / homo-oligomer blocks — the downloadable skill lists each field with its source table. Preview blocks, attached at serve time and subject to change (not described in the manuscript): deterministic_features.library_designed_topology (the DeepTMHMM 1.0.24 topology of the protein each library member's designed CDS actually encodes, matched by exact sequence; often an isoform, not the canonical), deterministic_features.library_designed_structure (which structure model to render for each library member, with the residue offset that maps construct residues onto it), and deterministic_features.bindome (binder-design sites recovered from Bindome's BindCraft designs, kept separate from surface_bind). Each is present only for genes with data.

    curl -s https://api.deliverome.org/surfaceome/v1/genes/ERBB2 | jq '.executive_summary.surface_accessibility, .confidence'

  • GET/v1/genes/{SYMBOL}/evidence

    The evidence ledger for one gene: { gene, evidence: [...], papers: {...} }. Each evidence entry carries the verbatim quote, its source provenance (PMC / PMID / DOI / URL), evidence tier, and the cross-planner duplicate links; `papers` is NCBI citation metadata (title, authors, journal, year, PMID / PMCID / DOI) keyed by the source_id the spans cite, so a consumer can render a reference without a second lookup. 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), (.papers | length)'

  • GET/v1/genes/{SYMBOL}.md

    Rich Markdown brief for one gene (text/markdown), served from R2: the record as readable prose plus reanalysis extras that are not in the JSON — canonical, isoform and ortholog sequences, per-residue DeepTMHMM topology and AlphaFold links. The most agent-friendly single-gene artifact. The symbol is matched exactly, so use the canonical HGNC case (e.g. C11orf24); a wrong-case symbol 404s `markdown_not_found`. Cached 60 s.

    curl -s https://api.deliverome.org/surfaceome/v1/genes/ERBB2.md | head -5

  • GET/v1/orthologs/{SYMBOL}~401 B

    Mouse and cynomolgus orthologs for a human gene from Ensembl Compara release 115 (`release_version: "ensembl_compara_115"`; broad genome-wide raw Compara — full-length % identity + orthology type, ~5k genes). Any well-formed symbol returns 200; a gene with no orthologs on file gets `orthologs: []`, not a 404. 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)'

  • GET/v1/internalization/{SYMBOL}

    Full InternalizationRecord for one gene: the sequence-prior grade (very_high … very_low) with per-isoform topology, motifs and reasoning under `model_priors`, the literature track under `literature`, and NCBI citation metadata under `papers`. Returns 200 with a `null` body when the gene is not in the internalization cohort. The per-gene grade is also on each /v1/catalog row as `intern`.

    curl -s https://api.deliverome.org/surfaceome/v1/internalization/ERBB2 | jq '(.model_priors[] | {model, overall_grade}), .literature.overall_grade'

  • GET/v1/tag-sites/{SYMBOL}

    TaggedSitesFile for one gene: engineered epitope / tag insertion points — deterministic loop, disorder and terminal candidates plus literature-validated sites. Returns 200 with `has_data: false` and `sites: []` when the gene has none. A literature site's optional `position_frame` names the proteoform frame the citation numbered in ("mature", "isoform:…") when it was not the protein's own.

    curl -s https://api.deliverome.org/surfaceome/v1/tag-sites/ERBB2 | jq '.has_data, (.sites | length), (.sites[0] | {site_kind, residue_label})'

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}/revisions

    Every 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/releases

    Numbered 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'

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/replicates

    Every 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}/replicates

    The 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/v1

    Self-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/sizes

    Approximate 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

When “Cell-state induced” is active, the catalog reveals sub-axes by induction_trigger:

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.

Caching · Cache-Control: max-age=60 (60 s) for list and index endpoints (/v1, /v1/health, /v1/genes, /v1/catalog, /v1/releases, …), per-gene triage, catalog rows, tag sites and the .md briefs; max-age=86400 (one day) for per-gene records, evidence ledgers, benchmark, orthologs, internalization and the TSV exports; max-age=31536000, immutable (one year) for revision bodies and DOI-published releases. Not-found responses cache for 60 s. Build-time consumers should use cache: "force-cache" so the response is baked into the static artifact. If a server-side lookup used to enrich the record hiccups, the response still ships 200 but carries X-Surfaceome-Degraded (a comma-separated list of the fields that may be stale/null) and Cache-Control: no-store — retry rather than caching it yourself.

Rate limits · Reads are rate-limited per client IP. The limits are generous — they exist to bound cost under abuse, not to gate access — and tighter on the heavy endpoints (/v1/catalog, every *.tsv export, and /v1/releases/{version}). /v1/health is never limited. Over the limit, the API answers 429 with {"error":"rate_limited"} and Retry-After: 60 — wait that long before retrying. For bulk work, pace requests (a couple per second is plenty), prefer the TSV exports or /v1/catalog over thousands of per-gene calls, and send an identifying User-Agent.

Cite & licence · Cite the preprint, doi:10.64898/2026.10.18.759859. Data served by this API is CC0 1.0: cite the data concept DOI 10.5281/zenodo.20805383 (or a numbered release's version DOI, listed by /v1/releases). The code, including this Worker and site, is MIT — 10.5281/zenodo.22116981. See Data and code availability.

Schema · Per-gene records validate against the SurfaceomeRecord Pydantic schema at src/accessible_surfaceome/tools/_shared/models.py in the source repo. Fields not present in older records are absent on the wire — use optional-chaining when reading.

Sizes · The ~size on each endpoint is an approximate response size computed from live D1 row counts and LENGTH(...) sums (/v1/meta/sizes), baked in at build time so it refreshes on each deploy rather than being hand-maintained. Variable-length text is summed exactly; JSON/TSV structural overhead is estimated.

For agents · Start at /v1 (a self-describing index of every endpoint) or download the skill above. The site root also serves an llms.txt that links the API, the skill, and the per-gene record + Markdown mirror.

Source · Worker code at cloudflare/workers/surfaceome_api/src/index.js; D1 schema at cloudflare/d1_public_schema.sql.