API Documentation

RESTful API endpoints for programmatic access to gene data

Available Endpoints
GET /health

Health check endpoint

Response: 
{
  "status": "healthy",
  "service": "NCBI Gene MCP Client"
}
POST /search/genes

Search for genes using a query

Request Body (form-data): 
{
  "query": "BRCA1[gene] AND human[organism]",
  "max_results": 20
}
Response: 
{
  "success": true,
  "data": {
    "count": 1,
    "ids": ["672"],
    "query_translation": "BRCA1[gene] AND \"Homo sapiens\"[Organism]",
    "query": "BRCA1[gene] AND human[organism]"
  }
}
GET /gene/{gene_id}

Get detailed information for a specific gene

Example: GET /api/gene/672
Response: 
{
  "success": true,
  "data": {
    "gene_id": "672",
    "name": "BRCA1",
    "description": "BRCA1 DNA repair associated",
    "organism": "Homo sapiens",
    "chromosome": "17",
    "map_location": "17q21.31",
    "gene_type": "genomic",
    "other_aliases": ["BRCAI", "BRCC1", "BROVCA1"],
    "summary": "This gene encodes a 190 kD nuclear phosphoprotein..."
  }
}
POST /search/symbol

Search genes by symbol with optional organism filter

Request Body (form-data): 
{
  "symbol": "BRCA1",
  "organism": "human"  // optional
}
Response: 
{
  "success": true,
  "data": {
    "genes": [
      {
        "gene_id": "672",
        "name": "BRCA1",
        "description": "BRCA1 DNA repair associated",
        "organism": "Homo sapiens",
        "chromosome": "17",
        ...
      }
    ],
    "count": 1,
    "symbol": "BRCA1",
    "organism": "human"
  }
}
GET /examples

Get example queries and gene IDs for testing

Response: 
{
  "search_examples": [
    "BRCA1[gene] AND human[organism]",
    "breast cancer[disease] AND human[organism]",
    "TP53",
    "diabetes[disease]",
    "APOE[gene]"
  ],
  "gene_examples": [
    {"id": "672", "name": "BRCA1", "description": "Breast cancer gene"},
    {"id": "7157", "name": "TP53", "description": "Tumor suppressor"},
    ...
  ],
  "organisms": ["human", "Homo sapiens", "mouse", "Mus musculus", ...]
}
Error Handling

All API endpoints return JSON responses. In case of errors:

Error Response: 
{
  "detail": "Error message describing what went wrong"
}

Common HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 404 - Not Found (invalid gene ID)
  • 500 - Internal Server Error (NCBI API issues)
Usage Examples
cURL Examples
# Search for genes
curl -X POST "http://localhost:8000/api/search/genes" \
     -F "query=BRCA1" \
     -F "max_results=10"

# Get gene information
curl "http://localhost:8000/api/gene/672"

# Search by symbol
curl -X POST "http://localhost:8000/api/search/symbol" \
     -F "symbol=BRCA1" \
     -F "organism=human"
Python Examples
import requests

# Search for genes
response = requests.post(
    "http://localhost:8000/api/search/genes",
    data={"query": "BRCA1", "max_results": 10}
)
print(response.json())

# Get gene information
response = requests.get("http://localhost:8000/api/gene/672")
gene_data = response.json()["data"]
print(f"Gene: {gene_data['name']}")
JavaScript Examples
// Search for genes
const formData = new FormData();
formData.append('query', 'BRCA1');
formData.append('max_results', '10');

fetch('/api/search/genes', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

// Get gene information
fetch('/api/gene/672')
    .then(response => response.json())
    .then(data => console.log(data.data));
Rate Limiting

This API follows NCBI's guidelines for rate limiting:

  • Without API key: Maximum 3 requests per second
  • With API key: Maximum 10 requests per second
  • Recommendation: Add delays between requests to avoid hitting limits
Note: If you exceed the rate limit, requests may be delayed or return error responses.