Skip to main content

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 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/ERBB2 | 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,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 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, 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 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 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 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 ~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 -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 ~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 B

    Liveness check. Returns the count of deep-dive SurfaceomeRecords on file.

    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, 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.

    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: [...] }, 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 B

    Mouse 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}/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'

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

    Current release, source provenance, coverage and excluded identifiers.

    curl -s https://api.deliverome.org/surfaceome/v1/contact-sites/releases/current
  • GET/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}/evidence

    Up 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/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 · List endpoints (/v1/health, /v1/genes, /v1/catalog, /v1/triage/*) ship Cache-Control: max-age=60; per-gene records, benchmark, and ortholog endpoints ship max-age=86400 (one day). 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.

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.