@wentorai/research-plugins 1.3.2 → 1.4.0

package/skills/domains/biomedical/clinicaltrials-api-v2/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: clinicaltrials-api-v2
+description: "Search and analyze clinical trials via the ClinicalTrials.gov v2 API"
+metadata:
+  openclaw:
+    emoji: "🏥"
+    category: "domains"
+    subcategory: "biomedical"
+    keywords: ["clinical trials", "ClinicalTrials.gov", "medical research", "study design", "FDA", "drug trials"]
+    source: "https://clinicaltrials.gov/data-api/about-api"
+---
+
+# ClinicalTrials.gov v2 API Guide
+
+## Overview
+
+ClinicalTrials.gov is the world's largest clinical trial registry, maintained by the U.S. National Library of Medicine (NLM) at NIH. It contains over 576,000 study records from 220+ countries covering interventional trials, observational studies, and expanded access programs. The v2 API provides structured JSON access with field-level filtering, cursor-based pagination, and statistics endpoints.
+
+Key v2 improvements over the legacy API: JSON-native responses, sparse field selection via the `fields` parameter, `nextPageToken` pagination, and dedicated statistics endpoints. Study data is organized into `protocolSection` (sponsor-submitted) and `derivedSection` (NLM-computed).
+
+## Authentication
+
+No authentication required. All endpoints are publicly accessible without API keys or registration. Users should comply with NCBI usage policies and maintain reasonable request rates.
+
+## Core Endpoints
+
+### Search Studies
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/studies`
+- **Parameters**:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| query.term | string | No | Free-text search across all fields |
+| query.cond | string | No | Condition or disease filter |
+| query.intr | string | No | Intervention or treatment filter |
+| query.spons | string | No | Sponsor or collaborator filter |
+| filter.overallStatus | string | No | `RECRUITING`, `COMPLETED`, `ACTIVE_NOT_RECRUITING`, etc. |
+| filter.phase | string | No | `EARLY_PHASE1`, `PHASE1`, `PHASE2`, `PHASE3`, `PHASE4`, `NA` |
+| filter.geo | string | No | Geographic filter (`distance(lat,lng,dist)`) |
+| fields | string | No | Comma-separated fields for sparse response |
+| sort | string | No | Sort field and direction (e.g., `LastUpdatePostDate:desc`) |
+| pageSize | int | No | Results per page (default 10, max 1000) |
+| pageToken | string | No | Cursor token for next page |
+| format | string | No | `json` (default) or `csv` |
+
+- **Example**:
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/studies?query.cond=diabetes&query.intr=metformin&pageSize=1&fields=NCTId,BriefTitle,OverallStatus"
+```
+
+- **Response**:
+
+```json
+{
+  "studies": [{
+    "protocolSection": {
+      "identificationModule": {
+        "nctId": "NCT06649773",
+        "briefTitle": "The Experiment of Noiiglutide Injection in Type 2 Diabetes Patients"
+      },
+      "statusModule": { "overallStatus": "ACTIVE_NOT_RECRUITING" }
+    }
+  }],
+  "nextPageToken": "ZVNj7o2Elu8o3lpo..."
+}
+```
+
+Full responses include `protocolSection` with: `identificationModule` (NCT ID, titles, organization), `statusModule` (status, dates), `descriptionModule` (summary), `conditionsModule`, `designModule` (type, phases, enrollment), `armsInterventionsModule`, `eligibilityModule` (criteria, sex, age), `outcomesModule`, and `contactsLocationsModule`.
+
+### Get Single Study
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/studies/{nctId}`
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/studies/NCT04280705?fields=NCTId,BriefTitle,OverallStatus,Phase,LeadSponsorName,EnrollmentCount,Condition,InterventionName"
+```
+
+```json
+{
+  "protocolSection": {
+    "identificationModule": {
+      "nctId": "NCT04280705",
+      "briefTitle": "Adaptive COVID-19 Treatment Trial (ACTT)"
+    },
+    "statusModule": {
+      "overallStatus": "COMPLETED",
+      "startDateStruct": { "date": "2020-02-21" },
+      "completionDateStruct": { "date": "2020-05-21" }
+    },
+    "sponsorCollaboratorsModule": {
+      "leadSponsor": { "name": "National Institute of Allergy and Infectious Diseases (NIAID)" }
+    },
+    "conditionsModule": { "conditions": ["COVID-19"] },
+    "designModule": { "phases": ["PHASE3"], "enrollmentInfo": { "count": 1062 } },
+    "armsInterventionsModule": {
+      "interventions": [{ "name": "Placebo" }, { "name": "Remdesivir" }]
+    }
+  }
+}
+```
+
+### Database Statistics
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/stats/size`
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/stats/size"
+```
+
+```json
+{
+  "totalStudies": 576554,
+  "averageSizeBytes": 17186,
+  "largestStudies": [
+    { "id": "NCT02723955", "sizeBytes": 3596689 },
+    { "id": "NCT03688620", "sizeBytes": 2865033 }
+  ]
+}
+```
+
+### Field Value Statistics
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/stats/fieldValues/{fieldName}`
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/stats/fieldValues/Phase"
+```
+
+```json
+{
+  "type": "ENUM",
+  "piece": "Phase",
+  "field": "protocolSection.designModule.phases",
+  "missingStudiesCount": 136632,
+  "topValues": [
+    { "value": "NA", "studiesCount": 222829 },
+    { "value": "PHASE2", "studiesCount": 87478 },
+    { "value": "PHASE1", "studiesCount": 63716 },
+    { "value": "PHASE3", "studiesCount": 48700 },
+    { "value": "PHASE4", "studiesCount": 34911 },
+    { "value": "EARLY_PHASE1", "studiesCount": 6179 }
+  ]
+}
+```
+
+## Rate Limits
+
+No formal rate limits are published for the v2 API. Follow NCBI usage guidelines: stay under 3 requests/second without an API key, up to 10/second with one. For bulk data access, use the AACT relational database (https://aact.ctti-clinicaltrials.org/) or downloadable flat files rather than paginating through the full API.
+
+## Academic Use Cases
+
+- **Systematic reviews**: Use `query.cond` + `query.intr` + `filter.overallStatus=COMPLETED` to build PRISMA-compliant trial inventories. Paginate with `nextPageToken` to collect all records, then extract outcomes and enrollment for quantitative synthesis.
+- **Landscape mapping**: Combine search with `stats/fieldValues` to map phase distributions, sponsor concentration, and geographic spread for a therapeutic area -- useful for identifying evidence gaps in grant proposals.
+- **Recruitment tracking**: Filter by `RECRUITING` status and `filter.geo` to find active enrollment opportunities. Automate periodic queries for new trials in your domain.
+
+## Code Examples
+
+### Paginated Collection for Systematic Review
+
+```python
+import requests, time
+
+def collect_trials(condition, intervention, status="COMPLETED"):
+    base = "https://clinicaltrials.gov/api/v2/studies"
+    studies, token = [], None
+    while True:
+        params = {
+            "query.cond": condition, "query.intr": intervention,
+            "filter.overallStatus": status, "pageSize": 100,
+            "fields": "NCTId,BriefTitle,Phase,EnrollmentCount,CompletionDate",
+        }
+        if token:
+            params["pageToken"] = token
+        data = requests.get(base, params=params).json()
+        studies.extend(data.get("studies", []))
+        token = data.get("nextPageToken")
+        if not token:
+            break
+        time.sleep(0.34)
+    return studies
+
+trials = collect_trials("type 2 diabetes", "metformin")
+print(f"Collected {len(trials)} completed metformin T2D trials")
+```
+
+### Sponsor and Phase Analysis
+
+```python
+import requests
+from collections import Counter
+
+params = {"query.cond": "Alzheimer's Disease", "pageSize": 100,
+          "fields": "NCTId,Phase,LeadSponsorName"}
+data = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params).json()
+
+phases, sponsors = Counter(), Counter()
+for s in data["studies"]:
+    p = s["protocolSection"]
+    for ph in p.get("designModule", {}).get("phases", []):
+        phases[ph] += 1
+    sponsors[p.get("sponsorCollaboratorsModule", {})
+              .get("leadSponsor", {}).get("name", "Unknown")] += 1
+
+for ph, n in phases.most_common():
+    print(f"{ph}: {n}")
+```
+
+## References
+
+- v2 API reference: https://clinicaltrials.gov/data-api/api
+- About the API: https://clinicaltrials.gov/data-api/about-api
+- AACT database (bulk access): https://aact.ctti-clinicaltrials.org/
+- WHO ICTRP: https://trialsearch.who.int/
+- NCBI usage policies: https://www.ncbi.nlm.nih.gov/home/about/policies/

package/skills/domains/biomedical/enrichr-api/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: enrichr-api
+description: "Perform gene set enrichment analysis using the Enrichr API"
+metadata:
+  openclaw:
+    emoji: "🔬"
+    category: "domains"
+    subcategory: "biomedical"
+    keywords: ["gene set enrichment", "pathway analysis", "GO terms", "KEGG", "Enrichr", "functional analysis"]
+    source: "https://maayanlab.cloud/Enrichr"
+---
+
+# Enrichr Gene Set Enrichment Analysis API
+
+## Overview
+
+Enrichr is the most widely used gene set enrichment analysis tool, developed by the Ma'ayan Lab at the Icahn School of Medicine at Mount Sinai. It tests whether a user-supplied gene list is statistically over-represented in curated gene set libraries spanning pathways, ontologies, transcription factor targets, disease associations, and cell types. The API provides access to 225 background libraries covering over 500,000 annotated gene sets. Free, no authentication required.
+
+## Two-Step Workflow
+
+Enrichr uses a submit-then-query pattern:
+
+1. **POST gene list** to `/addList` -- returns a `userListId` token
+2. **GET enrichment** from `/enrich` using that token and a chosen library
+
+The `userListId` persists on the server, so you can run multiple library queries against the same submission without re-uploading.
+
+## Core Endpoints
+
+### Base URL
+
+```
+https://maayanlab.cloud/Enrichr
+```
+
+### Step 1: Submit Gene List
+
+```bash
+curl -X POST "https://maayanlab.cloud/Enrichr/addList" \
+  -F "list=BRCA1
+BRCA2
+TP53
+EGFR
+MYC
+PTEN
+AKT1
+KRAS
+PIK3CA
+RAF1" \
+  -F "description=cancer_genes"
+```
+
+**Response:**
+
+```json
+{
+  "shortId": "8619200cc78f1513ff1029a04af90ad7",
+  "userListId": 124544426
+}
+```
+
+Genes are newline-separated. The request must use `multipart/form-data` (the `-F` flag), not `application/x-www-form-urlencoded`.
+
+### Step 2: Retrieve Enrichment Results
+
+```bash
+curl "https://maayanlab.cloud/Enrichr/enrich?userListId=124544426&backgroundType=KEGG_2021_Human"
+```
+
+**Response (first 3 of 143 results):**
+
+```json
+{
+  "KEGG_2021_Human": [
+    [1, "Breast cancer", 3.37e-22, 198530.0, 9815800.25,
+     ["PIK3CA","MYC","PTEN","AKT1","KRAS","BRCA1","BRCA2","RAF1","TP53","EGFR"],
+     4.82e-20, 0, 0],
+    [2, "Endometrial cancer", 1.35e-19, 1595.2, 69306.12,
+     ["PIK3CA","MYC","PTEN","AKT1","KRAS","RAF1","TP53","EGFR"],
+     9.68e-18, 0, 0],
+    [3, "Central carbon metabolism in cancer", 6.66e-19, 1285.68, 53809.88,
+     ["PIK3CA","MYC","PTEN","AKT1","KRAS","RAF1","TP53","EGFR"],
+     3.17e-17, 0, 0]
+  ]
+}
+```
+
+Each result array contains: `[rank, term_name, p_value, z_score, combined_score, overlapping_genes, adjusted_p_value, old_p_value, old_adjusted_p_value]`.
+
+### View Submitted Gene List
+
+```bash
+curl "https://maayanlab.cloud/Enrichr/view?userListId=124544426"
+```
+
+```json
+{
+  "genes": ["PIK3CA","MYC","AKT1","PTEN","BRCA1","KRAS","BRCA2","EGFR","TP53","RAF1"],
+  "description": "cancer_genes"
+}
+```
+
+### Export Results as TSV
+
+```bash
+curl "https://maayanlab.cloud/Enrichr/export?userListId=124544426&backgroundType=KEGG_2021_Human&filename=results" \
+  -o enrichr_results.txt
+```
+
+### List Available Libraries
+
+```bash
+curl "https://maayanlab.cloud/Enrichr/datasetStatistics"
+```
+
+Returns metadata for all 225 libraries, each entry containing `libraryName`, `numTerms`, `geneCoverage`, and `genesPerTerm`.
+
+## Available Libraries (225 Total)
+
+### Pathway Databases
+
+| Library | Terms | Genes |
+|---------|-------|-------|
+| KEGG_2026 | 352 | 8,110 |
+| KEGG_2021_Human | 320 | 8,078 |
+| WikiPathways_2024_Human | 829 | 8,281 |
+| Reactome_Pathways_2024 | 2,105 | 11,671 |
+| BioCarta_2016 | 237 | 1,348 |
+
+### Gene Ontology
+
+| Library | Terms | Genes |
+|---------|-------|-------|
+| GO_Biological_Process_2025 | 5,343 | 14,674 |
+| GO_Molecular_Function_2025 | 1,174 | 11,484 |
+| GO_Cellular_Component_2025 | 468 | 11,501 |
+
+### Disease and Phenotype
+
+| Library | Terms | Genes |
+|---------|-------|-------|
+| DisGeNET | 9,828 | 17,464 |
+| GWAS_Catalog_2025 | 2,369 | 15,030 |
+| ClinVar_2025 | 609 | 3,481 |
+| OMIM_Disease | 90 | 1,759 |
+| Human_Phenotype_Ontology | 1,779 | 3,096 |
+
+### Transcription Factor and Epigenomics
+
+| Library | Terms | Genes |
+|---------|-------|-------|
+| ChEA_2022 | 757 | 18,365 |
+| ENCODE_TF_ChIP-seq_2015 | 816 | 26,382 |
+| JASPAR_PWM_Human_2025 | 675 | 18,518 |
+
+### Cell Type and Tissue
+
+| Library | Terms | Genes |
+|---------|-------|-------|
+| CellMarker_2024 | 1,692 | 12,642 |
+| ARCHS4_Tissues | 108 | 21,809 |
+| Human_Gene_Atlas | 84 | 13,373 |
+
+### Cancer and Drug
+
+| Library | Terms | Genes |
+|---------|-------|-------|
+| MSigDB_Hallmark_2020 | 50 | 4,383 |
+| MSigDB_Oncogenic_Signatures | 189 | 11,250 |
+| DGIdb_Drug_Targets_2024 | 659 | 2,513 |
+
+## Rate Limits
+
+- No authentication or API key required
+- No officially published rate limits, but automated queries should include reasonable delays (1-2 seconds between requests)
+- Very large gene lists (>3,000 genes) may time out on some libraries
+- The `userListId` persists server-side; avoid re-submitting the same list repeatedly
+
+## Academic Use Cases
+
+- **Differential expression follow-up**: Submit DEGs from RNA-seq to identify enriched pathways and GO terms
+- **GWAS hit annotation**: Map GWAS-significant genes to disease phenotypes via DisGeNET or GWAS_Catalog
+- **Drug target discovery**: Cross-reference gene signatures against DGIdb_Drug_Targets for druggable candidates
+- **Transcription factor analysis**: Identify upstream regulators via ChEA or ENCODE TF libraries
+
+## Python Usage
+
+```python
+import requests
+
+ENRICHR_URL = "https://maayanlab.cloud/Enrichr"
+
+
+def submit_gene_list(genes: list[str], description: str = "") -> int:
+    """Submit a gene list to Enrichr, return userListId."""
+    payload = {
+        "list": (None, "\n".join(genes)),
+        "description": (None, description),
+    }
+    resp = requests.post(f"{ENRICHR_URL}/addList", files=payload)
+    resp.raise_for_status()
+    return resp.json()["userListId"]
+
+
+def get_enrichment(user_list_id: int, library: str) -> list[dict]:
+    """Retrieve enrichment results for a given library."""
+    resp = requests.get(
+        f"{ENRICHR_URL}/enrich",
+        params={"userListId": user_list_id, "backgroundType": library},
+    )
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for entry in data.get(library, []):
+        results.append({
+            "rank": entry[0],
+            "term": entry[1],
+            "p_value": entry[2],
+            "z_score": entry[3],
+            "combined_score": entry[4],
+            "genes": entry[5],
+            "adj_p_value": entry[6],
+        })
+    return results
+
+
+def get_libraries() -> list[dict]:
+    """List all available Enrichr libraries."""
+    resp = requests.get(f"{ENRICHR_URL}/datasetStatistics")
+    resp.raise_for_status()
+    return resp.json()["statistics"]
+
+
+# Example: enrichment analysis of cancer-related genes
+genes = ["BRCA1", "BRCA2", "TP53", "EGFR", "MYC",
+         "PTEN", "AKT1", "KRAS", "PIK3CA", "RAF1"]
+
+list_id = submit_gene_list(genes, "cancer_genes")
+print(f"Submitted gene list, ID: {list_id}")
+
+# Query KEGG pathways
+kegg = get_enrichment(list_id, "KEGG_2021_Human")
+print(f"\nTop 5 KEGG pathways ({len(kegg)} total):")
+for r in kegg[:5]:
+    print(f"  {r['rank']}. {r['term']}")
+    print(f"     p={r['p_value']:.2e}, adj_p={r['adj_p_value']:.2e}, "
+          f"genes={','.join(r['genes'][:5])}...")
+
+# Query GO Biological Process
+go_bp = get_enrichment(list_id, "GO_Biological_Process_2023")
+print(f"\nTop 5 GO Biological Processes ({len(go_bp)} total):")
+for r in go_bp[:5]:
+    print(f"  {r['rank']}. {r['term']}")
+    print(f"     p={r['p_value']:.2e}, genes={','.join(r['genes'])}")
+```
+
+## References
+
+- [Enrichr Web App](https://maayanlab.cloud/Enrichr)
+- [Enrichr API Docs](https://maayanlab.cloud/Enrichr/help#api)
+- Chen, E.Y. et al. (2013). "Enrichr: interactive and collaborative HTML5 gene list enrichment analysis tool." *BMC Bioinformatics* 14:128.
+- Kuleshov, M.V. et al. (2016). "Enrichr: a comprehensive gene set enrichment analysis web server 2016 update." *Nucleic Acids Res.* 44(W1).
+- Xie, Z. et al. (2021). "Gene Set Knowledge Discovery with Enrichr." *Current Protocols* 1(3):e90.

package/skills/domains/biomedical/ensembl-rest-api/SKILL.md

@@ -0,0 +1,204 @@
+---
+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**: Retrieve consequence types and clinical significance for GWAS rsIDs.
+- **ID mapping**: Map between Ensembl, UniProt, RefSeq, and HGNC identifiers.
+- **Primer design**: Fetch genomic sequences with flanking regions for PCR or CRISPR targeting.
+- **Comparative genomics**: Query homology endpoints for orthologs across species.
+
+## Code Examples (Python)
+
+### Gene Lookup and Sequence Retrieval
+
+```python
+import requests
+
+BASE = "https://rest.ensembl.org"
+HEADERS = {"Content-Type": "application/json"}
+
+gene = requests.get(f"{BASE}/lookup/symbol/homo_sapiens/BRCA1", headers=HEADERS).json()
+print(f"{gene['display_name']} ({gene['id']}) chr{gene['seq_region_name']}:{gene['start']}-{gene['end']}")
+
+seq = requests.get(f"{BASE}/sequence/id/{gene['id']}?type=cds", headers=HEADERS).json()
+print(f"CDS length: {len(seq['seq'])} bp")
+```
+
+### Batch ID Lookup (POST)
+
+```python
+import requests
+
+ids = ["ENSG00000012048", "ENSG00000141510", "ENSG00000157764"]  # BRCA1, TP53, BRAF
+resp = requests.post(
+    "https://rest.ensembl.org/lookup/id",
+    headers={"Content-Type": "application/json", "Accept": "application/json"},
+    json={"ids": ids}
+)
+for ens_id, info in resp.json().items():
+    print(f"{info['display_name']:10s} chr{info['seq_region_name']}:{info['start']}-{info['end']}")
+```
+
+### Variant Annotation Pipeline
+
+```python
+import requests
+
+for rsid in ["rs699", "rs1042522", "rs334"]:
+    v = requests.get(
+        f"https://rest.ensembl.org/variation/homo_sapiens/{rsid}",
+        headers={"Content-Type": "application/json"}
+    ).json()
+    loc = v["mappings"][0]["location"] if v.get("mappings") else "N/A"
+    print(f"{v['name']:12s} {v['var_class']:5s} {v['most_severe_consequence']:25s} {loc}")
+```
+
+## References
+
+- REST API docs: https://rest.ensembl.org/documentation
+- Ensembl browser: https://www.ensembl.org
+- gget toolkit (built on Ensembl REST): https://pachterlab.github.io/gget/
+- GRCh37 archive API: https://grch37.rest.ensembl.org