POLYMER GENOMICS
API Reference
ViewerAtlasClaimsNewsroomDev / API

API Reference

The Polymer Genomics API serves curated genomic annotations at base-pair resolution. All endpoints return JSON with 1-based closed coordinates by default.

BASE URL
https://api.polymerbio.org

API

GET/v1/regions/{build}/{region}

Query Region

The primary endpoint. Returns all annotation layers for a genomic region. Layers are returned as GRanges objects with metadata columns.

PARAMETERS
buildstring*Genome build: hg38 or hg37
regionstring*Genomic region, e.g. chr17:7668421-7687490
layersstringComma-separated layer keys to include
coordsstring = 1basedCoordinate system: 1based or 0based
limitintegerMax features per layer
GET/v1/genes/{build}/{symbol}

Get Gene

Look up a gene by symbol. Returns transcript features as GRanges with exon, UTR, and CDS annotations.

PARAMETERS
buildstring*Genome build
symbolstring*Gene symbol, e.g. TP53, BRCA1
GET/v1/sequence/{build}/{region}

Get Sequence

Retrieve the raw DNA sequence for a genomic region. Returns an uppercase nucleotide string.

PARAMETERS
buildstring*Genome build
regionstring*Genomic region
coordsstring = 1basedCoordinate system
GET/v1/probes/{build}/{probe_id}

Get Probe

Look up a single methylation array probe by ID. Returns coordinates, CpG context, and cross-mapping information.

PARAMETERS
buildstring*Genome build
probe_idstring*Probe identifier, e.g. cg00000029
POST/v1/probes/{build}/batch

Batch Probes

Look up multiple probes in a single request. Accepts a JSON body with an array of probe IDs.

PARAMETERS
buildstring*Genome build
probe_idsstring[]*Array of probe identifiers
GET/v1/layers

List Layers

List all available annotation layers. Returns metadata including row counts and versioning.

PARAMETERS
typestringFilter by layer type
buildstringFilter by genome build
activeboolean = trueOnly show active layers
GET/v1/aggregation/{build}/{region}

Aggregate Region

Get binned density and summary statistics for a region. Useful for visualizing large regions where individual features are too dense.

PARAMETERS
buildstring*Genome build
regionstring*Genomic region
layersstringLayer keys to aggregate
resolutioninteger = 1000Bin size in base pairs

Error Responses

All errors return a JSON object with a top-level error key containing code and message fields.

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description."
  }
}
401MISSING_API_KEY

Request did not include an API key. Pass your key via the X-API-Key header or api_key query parameter.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass via X-API-Key header."
  }
}
403INVALID_API_KEY

The provided API key is not valid or has been revoked.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is not valid."
  }
}
404NOT_FOUND

The requested resource does not exist. Check the path, genome build, gene symbol, or probe ID.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Gene 'FAKEGENE' not found in hg38."
  }
}
422VALIDATION_ERROR

The request parameters failed validation. The message field describes which parameter is invalid and why.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid region format. Expected chr1:100-200."
  }
}
429RATE_LIMITED

Too many requests. Back off and retry after the duration indicated in the Retry-After header.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}
500INTERNAL_ERROR

An unexpected server error occurred. If this persists, contact support with the request details.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}

MCP Server

The Polymer Genomics MCP server exposes 70 tools for AI agent consumption via the Model Context Protocol.60 reference tools query polymerbio.org over HTTP.10 compute tools run local R/Bioconductor analysis via subprocess.

Claude Code
    │
polymer-genomics MCP server (local)
    ├─ Reference tools (60)  → HTTP → api.polymerbio.org
    ├─ Compute tools  (10)  → Rscript subprocess
    └─ Session state        → /tmp/polymer/sessions/
INSTALL
uvx polymer-genomics-mcp
CLAUDE CODE CONFIG
{
  "mcpServers": {
    "polymer-genomics": {
      "command": "uvx",
      "args": ["polymer-genomics-mcp"]
    }
  }
}
METHYLATION PIPELINE WORKFLOW
load_idats → normalize → filter_probes → run_limma
                                            │
                                     volcano_plot / cluster_probes
                                            │
                              batch_probes → lookup_gene_expression
                              (annotate hits with reference tools)

Compute tools require local R with Bioconductor packages. Reference tools work without R.

Rscript -e "install.packages('BiocManager')
BiocManager::install(c('minfi','sesame','limma','matrixStats',
  'maxprobes','ComplexHeatmap','circlize'))
install.packages(c('jsonlite','ggplot2','svglite','base64enc'))"

Or use Docker: docker run polymerbio/methylation-toolkit

MCPload_idats

Load Illumina IDAT files and create an analysis session. Auto-detects array type (450K, EPIC, EPICv2) and runs initial QC.

PARAMETERS
idat_directorystring*Path to directory containing .idat files
sample_sheetstringPath to SampleSheet.csv (auto-detected if omitted)
MCPnormalize

Normalize methylation data. Supports openSesame (EPICv2), funnorm (450K/EPIC), quantile, noob, and raw.

PARAMETERS
session_idstring*Session ID from load_idats
methodstring = funnormNormalization method
MCPfilter_probes

Filter probes by QC criteria: detection p-value failures, SNP loci, sex chromosomes, and cross-reactive probes.

PARAMETERS
session_idstring*Session ID from load_idats
remove_snpboolean = trueRemove probes at known SNP positions
remove_sexboolean = trueRemove sex chromosome probes
remove_crossreactiveboolean = trueRemove cross-reactive probes
MCPrun_limma

Differential methylation analysis with limma eBayes on M-values. Returns top DMPs with delta-beta and adjusted p-values.

PARAMETERS
session_idstring*Session ID from load_idats
group_columnstring*Column name in sample sheet defining groups
contraststringExplicit contrast (e.g. "TET2_mut-WT"). Auto-detected for 2 groups
covariatesstring[]Covariate column names (e.g. ["Age", "Sex"])
fdrnumber = 0.05FDR threshold
MCPget_betas

Extract beta values (methylation levels 0–1). Returns inline for ≤100 probes, writes CSV for larger requests.

PARAMETERS
session_idstring*Session ID from load_idats
probesstring[]Probe IDs to extract (all if omitted)
MCPget_m_values

Extract M-values (log2 ratio, used for statistics). Returns inline for ≤100 probes, writes CSV for larger requests.

PARAMETERS
session_idstring*Session ID from load_idats
probesstring[]Probe IDs to extract (all if omitted)
MCPvolcano_plot

Generate a volcano plot from differential methylation results. Returns base64-encoded PNG for inline display.

PARAMETERS
session_idstring*Session ID from load_idats
fdrnumber = 0.05FDR threshold for significance line
deltabetanumber = 0.1Delta-beta threshold for effect size lines
MCPcluster_probes

Hierarchical clustering heatmap of the most variable probes. Returns base64-encoded PNG and cluster assignments.

PARAMETERS
session_idstring*Session ID from load_idats
n_probesinteger = 1000Number of top variable probes to include
distancestring = euclideanDistance metric
MCPsession_status

Check which pipeline steps have been completed, list generated files, and report creation time.

PARAMETERS
session_idstring*Session ID from load_idats
MCPcleanup_session_tool

Remove an analysis session and all its data. Deletes checkpoints, results, and plots permanently.

PARAMETERS
session_idstring*Session ID to remove
EXAMPLE — Query Region
curl "https://api.polymerbio.org/v1/regions/hg38/chr17:7668421-7687490?layers=gencode_v44,cpg_sites"
{
  "status": "complete",
  "coordinate_system": "1-based_closed",
  "query": {
    "build": "hg38",
    "chr": "chr17",
    "start": 7668421,
    "end": 7687490
EXAMPLE — Get Gene
curl "https://api.polymerbio.org/v1/genes/hg38/TP53"
{
  "status": "complete",
  "data": {
    "class": "GRanges",
    "seqnames": ["chr17", "chr17", ...],
    "ranges": {
      "start": [7668421, 7669609, ...],
      "end":   [7687490, 7669690, ...],
EXAMPLE — Get Sequence
curl "https://api.polymerbio.org/v1/sequence/hg38/chr17:7676000-7676100"
{
  "status": "complete",
  "data": {
    "sequence": "ATCGATCG...",
    "length": 101,
    "chr": "chr17",
    "start": 7676000,
    "end": 7676100
EXAMPLE — Get Probe
curl "https://api.polymerbio.org/v1/probes/hg38/cg00000029"
{
  "status": "complete",
  "data": {
    "probe_id": "cg00000029",
    "chr": "chr16",
    "start": 53434200,
    "end": 53434201,
    "cpg_context": "open_sea",
EXAMPLE — Batch Probes
curl -X POST "https://api.polymerbio.org/v1/probes/hg38/batch" \
  -H "Content-Type: application/json" \
  -d '{"probe_ids": ["cg00000029", "cg00000108"]}'
{
  "status": "complete",
  "data": {
    "cg00000029": { "chr": "chr16", ... },
    "cg00000108": { "chr": "chr4", ... }
  }
}
EXAMPLE — Search Genes
curl "https://api.polymerbio.org/v1/search?q=BRC&build=hg38"
{
  "results": [
    { "gene_symbol": "BRCA1" },
    { "gene_symbol": "BRCA2" },
    { "gene_symbol": "BRCC3" }
  ]
}
EXAMPLE — List Layers
curl "https://api.polymerbio.org/v1/layers?build=hg38"
[
  {
    "layer_key": "gencode_v44",
    "name": "GENCODE v44",
    "type": "gene_model",
    "build": "hg38",
    "row_count": 2800000,
    "active": true
EXAMPLE — Aggregate Region
curl "https://api.polymerbio.org/v1/aggregation/hg38/chr17:7000000-8000000?layers=cpg_sites&resolution=10000"
{
  "data": {
    "cpg_sites": {
      "bins": [
        { "bin_start": 7000000, "bin_end": 7010000, "count": 42, "density": 0.0042 },
        ...
      ],
      "resolution": 10000,
MCP WORKFLOW EXAMPLE
# In Claude Code, the agent calls tools conversationally:

> "Load my IDATs from ~/data/idats"

load_idats(idat_directory="~/data/idats")
→ {session_id: "a1b2c3d4e5f6", n_samples: 18,
   array_type: "EPICv2", n_probes: 1107072}

> "Normalize with openSesame and filter"

normalize(session_id="a1b2c3d4e5f6", method="opensesame")
→ {n_probes: 935620, method: "opensesame"}

filter_probes(session_id="a1b2c3d4e5f6")
→ {n_before: 935620, n_after: 795423,
   removed_counts: {snp: 42891, sex: 18234, ...}}

> "Find DMPs between TET2_mut and WT"

run_limma(session_id="a1b2c3d4e5f6",
          group_column="Sample_Group")
→ {n_dmps: 0, contrast: "TET2_mut-WT",
   n_tested: 795423, top_hits: [...]}

> "Make a volcano plot"

volcano_plot(session_id="a1b2c3d4e5f6")
→ {image_base64: "iVBOR...", n_significant: 0}

# Then annotate hits with reference tools:

batch_probes(build="hg38",
  probe_ids=["cg08796240", "cg06545761"])
→ gene symbols, coordinates, CpG context

lookup_gene_expression(build="hg38", symbol="VAC14")
→ GTEx 54-tissue expression profile
SESSION STATE MACHINE
load_idats → [raw.rds]
    │
normalize → [normalized.rds]
    │
filter_probes → [filtered.rds]
    │
run_limma → [dmps.rds, dmps.csv]
    │
volcano_plot / cluster_probes
  → [volcano.svg, heatmap.svg]
REFERENCE TOOLS (60)

All REST API endpoints above are also available as MCP tools with the same parameters. The MCP server wraps each endpoint so agents can call them without constructing HTTP requests.

Viewer·Atlas·Claims·Newsroom·Dev / API·Terms·Privacy·Data Sources
RESEARCH USE ONLY·© 2026 Polymer Genomics