Ensembl Rest ApiSAFE

🔬 A curated collection of 23,000+ agent skills for empirical research across 8 social science disciplines. | 精选 23,000+ AI Agent 技能库,覆盖8大社会科学学科的实证研究。CoPaper.AI 20分钟完成一篇可复现的规范实证论文,并支持用户上传 Skills。-- Maintained by CoPaper.AI from Stanford REAP.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ensembl-rest-api
description: "Query gene, sequence, and variant data via the Ensembl REST API"
metadata:
  openclaw:
    emoji: "🧬"
    category: "domains"
    subcategory: "biomedical"
    keywords: ["Ensembl", "gene lookup", "sequence retrieval", "genomics", "variant data", "bioinformatics"]
    source: "https://rest.ensembl.org"
---

# Ensembl REST API Guide

## Overview

Ensembl is a genome browser and annotation system maintained by EMBL-EBI and the Wellcome Sanger Institute, providing reference assemblies, gene annotations, variant data, and comparative genomics for over 300 vertebrate genomes. It is the genomic reference underpinning gget, PyEnsembl, and BioMart.

The REST API exposes Ensembl data via stateless HTTP. Researchers can look up genes by symbol or stable ID, retrieve genomic/cDNA/protein sequences, query variant annotations (rsIDs, clinical significance, consequences), access cross-references (HGNC, UniProt, RefSeq, OMIM), and obtain assembly metadata. Responses in JSON or XML.

## Authentication

No authentication required. All endpoints are publicly accessible. Users needing higher throughput can register for an API token.

## Core Endpoints

### lookup/symbol: Gene Lookup by Symbol

Retrieve gene metadata: coordinates, biotype, canonical transcript.

- **URL**: `GET https://rest.ensembl.org/lookup/symbol/{species}/{symbol}`
- **Parameters**:

| Parameter     | Type   | Required | Description                                      |
|---------------|--------|----------|--------------------------------------------------|
| species       | string | Yes      | Species name (e.g., `homo_sapiens`)              |
| symbol        | string | Yes      | Gene symbol (e.g., `BRCA1`, `TP53`)              |
| expand        | int    | No       | Set to 1 to include transcripts and translations |
| content-type  | string | Yes      | `application/json` or `text/xml`                 |

- **Example**:

```bash
curl "https://rest.ensembl.org/lookup/symbol/homo_sapiens/BRCA1?content-type=application/json"
```

- **Response** (actual):

```json
{
  "display_name": "BRCA1",
  "description": "BRCA1 DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1100]",
  "object_type": "Gene", "species": "homo_sapiens",
  "assembly_name": "GRCh38", "biotype": "protein_coding",
  "seq_region_name": "17", "start": 43044292, "end": 43170245, "strand": -1,
  "id": "ENSG00000012048", "canonical_transcript": "ENST00000357654.9"
}
```

### sequence/id: Sequence Retrieval

Retrieve genomic, cDNA, CDS, or protein sequences by Ensembl stable ID.

- **URL**: `GET https://rest.ensembl.org/sequence/id/{id}`
- **Parameters**:

| Parameter      | Type   | Required | Description                                           |
|----------------|--------|----------|-------------------------------------------------------|
| id             | string | Yes      | Ensembl stable ID (e.g., `ENSG00000012048`)           |
| type           | string | No       | `genomic`, `cdna`, `cds`, or `protein`                |
| expand_5prime  | int    | No       | Expand 5' flanking region by N bases                  |
| expand_3prime  | int    | No       | Expand 3' flanking region by N bases                  |
| content-type   | string | Yes      | `application/json` or `text/plain` (FASTA)            |

- **Example**:

```bash
curl "https://rest.ensembl.org/sequence/id/ENSG00000012048?content-type=application/json&type=genomic"
```

- **Response** (actual, seq truncated):

```json
{
  "id": "ENSG00000012048", "query": "ENSG00000012048",
  "desc": "chromosome:GRCh38:17:43044292:43170245:-1",
  "molecule": "DNA",
  "seq": "AAAGCGTGGGAATTACAGATAAATTAAAACTGTGGAACCCCTTTCCTCGGCTGCCGCCAAGGTGTTCGG..."
}
```

### xrefs/symbol: Cross-References

Map a gene symbol to Ensembl stable IDs and external database identifiers.

- **URL**: `GET https://rest.ensembl.org/xrefs/symbol/{species}/{symbol}`
- **Key params**: `species` (required), `symbol` (required), `external_db` (optional filter, e.g., `UniProt`)
- **Example**:

```bash
curl "https://rest.ensembl.org/xrefs/symbol/homo_sapiens/TP53?content-type=application/json"
```

- **Response** (actual): `[{"type":"gene","id":"ENSG00000141510"},{"type":"gene","id":"LRG_321"}]`

Use `xrefs/id/{id}` to expand an Ensembl ID to all external cross-references (UniProt, HGNC, RefSeq, OMIM).

### variation: Variant Annotation

Retrieve variant data by rsID: mappings, alleles, consequence, clinical significance.

- **URL**: `GET https://rest.ensembl.org/variation/{species}/{id}`
- **Key params**: `species` (required), `id` (required, e.g., `rs699`)
- **Example**:

```bash
curl "https://rest.ensembl.org/variation/homo_sapiens/rs699?content-type=application/json"
```

- **Response** (actual, synonyms truncated):

```json
{
  "name": "rs699", "var_class": "SNP",
  "most_severe_consequence": "missense_variant",
  "clinical_significance": ["benign"],
  "evidence": ["Frequency","1000Genomes","Cited","ESP","Phenotype_or_Disease","ExAC","TOPMed","gnomAD"],
  "mappings": [{"location":"1:230710048-230710048","allele_string":"A/G","strand":1,"assembly_name":"GRCh38"}]
}
```

### info/assembly: Assembly Metadata

- **URL**: `GET https://rest.ensembl.org/info/assembly/{species}`
- **Response** (actual): Returns `assembly_name` ("GRCh38.p14"), `assembly_date` ("2013-12"), `assembly_accession` ("GCA_000001405.29"), full `karyotype` array (1-22, X, Y, MT), and 347 `top_level_region` entries.

## Rate Limits

- **Without token**: 15 requests per second per IP.
- **With token**: higher limits available upon registration.
- **Response headers**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` on every response.
- **Batch POST endpoints** (`/lookup/id`, `/sequence/id`): accept up to 1000 IDs per request.
- **GRCh37 mirror**: `https://grch37.rest.ensembl.org`

## Academic Use Cases

- **Gene annotation**: Look up coordinates and biotypes for HGNC symbols to annotate RNA-seq results.
- **Variant interpretation**

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.