Skip to main content
The Deliverome ProjectSurfaceomev1.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, 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

232 lines · 16.1 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~4.8 MB

    Long-format TSV of the bench-restricted multi-model sweep: one row per (bench gene × model × variant) for the canonical bench_version. 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~4.7 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. Drives the SurfaceBench page's side-drawer.

    curl -s https://api.deliverome.org/surfaceome/v1/benchmark/matrix | jq '.n_genes, .models, .headline_variant, .alt_variants'

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, 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}~1.9 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. Returns every replicate's verdict + verdict_reasoning + per-call token usage + latency, plus the agent's overall majority verdict computed across replicates.

    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~616 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_v1 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_v1&replicate=1' | head -3

  • GET/v1/triage/export.tsv?run_id=genome_full_sonnet_ncbi_v1&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_v1&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~189 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}~120 KB

    Full SurfaceomeRecord JSON for one gene. Contains the executive summary, evidence-grade rationale, per-method observations, deterministic features, accessibility risks, and the full evidence ledger with citations.

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

  • GET/v1/orthologs/{SYMBOL}~403 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)'

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

Strictest tier — direct evidence (single or multi-method), high/moderate confidence, surface-dominant or mixed, low / moderate / unclear state-dependence, high/moderate surface accessibility, high/moderate evidence density. The high-confidence surface shortlist.

evidence_grade ∈ {direct_multi_method, direct_single_method}
AND confidence ∈ {high, moderate}
AND surface_specificity ∈ {surface_dominant, mixed}
AND state_dependence ∈ {low, moderate, unclear}
AND surface_accessibility ∈ {high, moderate}
AND evidence_density ∈ {high, moderate}
Likely

Broader shortlist — adds supportive-but-indirect evidence, mostly-intracellular surface fractions (e.g. SRC via lysosomal exocytosis, HMGB1 via DAMP release), and high / unclear / null state-dependence.

evidence_grade ∈ {direct_multi_method, direct_single_method, supportive_but_indirect}
AND surface_specificity ∈ {surface_dominant, mixed, mostly_intracellular}
AND surface_accessibility ∈ {high, moderate, low}
AND state_dependence ∈ {low, moderate, high, unclear, null}
Cell-state induced

Subset of Likely where surface presentation is induced by cell state (oncogenic transformation, stress, infection, immune activation). HSPA5, SRC, CD63, HMGB1, C3 land here.

passesLikely(f)
AND state_dependence ∈ {moderate, high, unclear, null}
AND (
  surface_call_reason ∈ {cell_state_induced, lysosomal_exocytosis}
  OR induction_trigger ∈ {oncogenic, immune, stress_hypoxia,
                          cell_death, infection}
)
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.

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.