GeDiPNet REST API

Programmatic access to gene-disease-pathway associations. Query genes, diseases, and biological pathways through a REST API.

1. Introduction

The GeDiPNet REST API provides programmatic access to curated gene-disease-pathway associations, regulatory networks, and biological annotations. Use it to:

  • Query gene information including diseases, pathways, transcription factors, miRNAs, and variants
  • Retrieve disease records with associated genes, external database IDs (MeSH, OMIM, HPO, Orphanet, MONDO), and PubMed evidence
  • Access pathway data from Reactome and KEGG
  • Search UniProt proteins and retrieve sequences and Pfam domains
  • Download complete datasets in TSV or JSON for offline analysis
  • Build custom bioinformatics pipelines and integrate GeDiPNet data into your workflows

2. Endpoints at a Glance

Every endpoint, relative to the base URL. Each one can be tried in the interactive console below, which also documents every parameter. See Response Format for how each paging style works.

MethodPathReturnsPaging
Genes
GET/genes/{symbol}Gene metadata: name, synonyms, chromosome and location, summary, cross-reference IDs—
GET/genes/{symbol}/diseasesAssociated diseases grouped by evidence (causal / unknown / text-mining) from ClinVar, GenCC, GWAS and PubTatorlimit only (max 200)
GET/genes/{symbol}/diseases/{disease}/evidencePubMed references and curated evidence text for one gene–disease pair—
GET/genes/{symbol}/pathwaysReactome or KEGG pathways containing the gene—
GET/genes/{symbol}/mirnasmiRNA–gene interactions (miRTarBase)page, limit
GET/genes/{symbol}/transcription-factorsTranscription factors regulating the gene (TRRUST)—
GET/genes/{symbol}/gene-ontologyGene Ontology terms, optionally filtered by categorypage, limit
GET/genes/{symbol}/proteinsUniProt entries with sequences and Pfam domains—
GET/genes/{symbol}/snpsdbSNP variantspage, limit
Diseases
GET/diseases/{disease_name}Disease terms with external IDs (MeSH, OMIM, HPO, Orphanet, MONDO), associated genes and referencespage, limit
POST/diseases/bulkLook up to 50 diseases in one request—
GET/download/diseasesFull disease → gene table as TSV or JSONoffset, limit
Pathways
GET/pathwaysBrowse or search Reactome / KEGG pathways by name, gene or diseasepage, limit
GET/pathways/{pathwayid}/genesGenes in a pathway (up to 500)—
GET/pathways/{pathwayid}/diseasesDiseases linked to the pathway's genes (up to 1000)—
GET/download/pathwaysPathway dataset as TSV or JSONoffset, limit
Proteins
GET/proteinsBrowse or search UniProt proteins (by name, gene, PDB or KEGG ID)page, limit
GET/proteins/{entry}One protein by UniProt accession: annotation, sequence, Pfam domains—
Utility
GET/testHealth check — no API key needed—
GET/openapi.jsonOpenAPI 3.0 specification — no API key needed—

3. Base URL

https://gedipnet.bicnirrh.res.in/api

All endpoints are relative to this base URL. For example:

https://gedipnet.bicnirrh.res.in/api/genes/BRCA1

OpenAPI specification

The full API description is available as an OpenAPI 3.0 file. Import it into Postman or Insomnia, or use it to generate a client library. No API key is needed to download it.

https://gedipnet.bicnirrh.res.in/api/openapi.json
Download OpenAPI spec (JSON)

4. Authentication

API Key Required: All endpoints (except the /test health check) require a valid API key. Keys are free and issued instantly upon registration.
Log in to Get Your Free API Key

How to send your key

MethodHow to sendRecommended?
Request header X-API-Key: your-key-here Yes — preferred
Query parameter ?api_key=your-key-here Fallback only
Interactive console below Click Authorize (top right of the console) and paste your key Yes — for browser testing

Getting your key in 3 steps

Step 1 — Register / Log in

Visit login.php and create a free account or log in with your existing credentials.

Step 2 — Generate Key

On your profile dashboard, click "Generate My API Key". Your unique key is created instantly.

Step 3 — Check Your Email

Your key is sent to your registered email address immediately.

Keep your key private. Don't share it publicly, commit it to GitHub, or embed it in client-side code on a public website. Prefer the X-API-Key header: a key sent as ?api_key= is part of the URL, so it can end up in server logs and browser history. You can revoke or regenerate your key at any time from your profile page. If you think it has been exposed, regenerate it, or contact us at gedipnet@bicnirrh.res.in.

5. Request Format

All API requests follow standard REST principles:

  • HTTP Methods: GET for retrieving data, POST for bulk operations
  • Content-Type: application/json (for POST requests)
  • Response Format: JSON
  • Character Encoding: UTF-8

Example GET request

Replace your-key-here with your API key — or log in and it's filled in for you.

curl -X GET "https://gedipnet.bicnirrh.res.in/api/genes/BRCA1" \ -H "X-API-Key: your-key-here" \ -H "accept: application/json"

Example POST request

curl -X POST "https://gedipnet.bicnirrh.res.in/api/diseases/bulk" \ -H "X-API-Key: your-key-here" \ -H "Content-Type: application/json" \ -d '{"diseases": ["breast cancer", "diabetes mellitus"]}'

6. Response Format

All responses are JSON objects with a status field (except TSV downloads):

{ "status": "success", "data": [ ... ], "pagination": { "page": 1, "limit": 50, "count_returned": 50, "has_more": true } }

Top-level fields

  • status — "success" or "error"
  • data — the payload; shape varies by endpoint. The pathway gene/disease endpoints return genes / diseases instead.
  • count / counts — number of records returned (not a database total) on endpoints that aren't paginated
  • pagination — present on paginated endpoints; its fields depend on the style below

Pagination styles

EndpointsQuery paramsPagination fields
/genes/{symbol}/mirnas, /genes/{symbol}/gene-ontology, /genes/{symbol}/snps, /pathways, /proteins page, limit page, limit, count_returned, has_more — no total count; keep requesting the next page while has_more is true
/diseases/{disease_name} page, limit current_page, per_page, total_terms, total_pages, has_next, has_prev
/download/diseases, /download/pathways (JSON format) offset, limit limit, offset, returned — increase offset by limit until fewer than limit rows come back

Other endpoints return their results in a single response. Some are capped at a fixed maximum; when a cap is reached, a note field says so (e.g. "Showing first 500 genes").

Disease response fields

  • disease_ids — array of { id, database, url } objects (MeSH, OMIM, HPO, Orphanet, MONDO, UMLS, MedGen)
  • main_sources — array of evidence source labels, e.g. ["Disgenet", "Orphanet"]
  • references — array of { pmid, url } objects linking to PubMed

7. Example Responses

Real responses from the live database, so you can see the shape before making a request. Long values are shortened with …. Most values come back as JSON strings, numeric columns included (e.g. "GeneID": "672"), so convert them in your code if you need numbers.

GET /genes/BRCA1

{ "status": "success", "data": { "GeneID": "672", "GeneName": "BRCA1 DNA repair associated", "Symbol": "BRCA1", "Synonyms": "BRCAI|BRCC1|BROVCA1|FANCS|IRIS|PNCA4|PPP1R53|PSCP|RNF53", "chromosome": "17", "map_location": "17q21.31", "summary": "This gene encodes a 190 kD nuclear phosphoprotein that plays a role in maintaining genomic stability, …", "other_ids": "MIM:113705|HGNC:HGNC:1100|Ensembl:ENSG00000012048|AllianceGenome:HGNC:1100", "disease_acronym_uniprot": "BROVCA1, FANCS, PNCA4" } }

8. Error Handling

Errors return the appropriate HTTP status code and a JSON body:

HTTP CodeMeaningExample Scenario
400Bad RequestInvalid database value, or missing/invalid diseases array on POST /diseases/bulk
401UnauthorizedNo API key was sent with the request
403ForbiddenAPI key is invalid or has been revoked
404Not FoundUnknown gene symbol, disease name or protein accession, or an unknown API path
405Method Not AllowedWrong HTTP method for an existing path (e.g. POST /genes/BRCA1)
429Too Many RequestsRate limit exceeded — 100 requests/hour per key
500Internal Server ErrorUnexpected server or database failure

Error bodies always have status and message. Some (authentication, rate limit, invalid database, unknown path) also repeat the HTTP status as code, but others omit it, so always read the HTTP status code itself:

{ "status": "error", "message": "Gene not found" }
{ "status": "error", "message": "Invalid or revoked API key.", "code": 403 }

9. Rate Limits

Limit: Each API key is restricted to 100 requests per hour. Exceeding this returns HTTP 429 with a retry_after_seconds field.

Rate limit headers

Every response includes these headers:

HeaderMeaning
X-RateLimit-LimitYour ceiling — always 100
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetUnix timestamp when your counter resets

Best practices:

  • Use POST /diseases/bulk to query up to 50 diseases in one request
  • Use download endpoints for large exports — one request per batch
  • Cache responses locally when running repeated analyses
  • Add a 100–300 ms delay between sequential requests in scripts
  • Need higher limits? Contact gedipnet@bicnirrh.res.in

Example: fetch every page and wait out the rate limit

Long jobs are where scripts usually break. This helper follows has_more page by page. On a 429 it waits for retry_after_seconds and then retries, instead of failing.

import time import requests API = "https://gedipnet.bicnirrh.res.in/api" HEADERS = {"X-API-Key": "your-key-here"} def get(path, params=None): """GET a path, waiting and retrying whenever the hourly rate limit is hit.""" while True: r = requests.get(API + path, headers=HEADERS, params=params, timeout=60) if r.status_code == 429: wait = r.json().get("retry_after_seconds", 60) print(f"Rate limit reached, waiting {wait} s ...") time.sleep(wait + 1) continue r.raise_for_status() return r.json() def get_all_pages(path, params=None, limit=100): """Collect every row from an endpoint that uses page / limit / has_more.""" params = dict(params or {}, limit=limit) rows, page = [], 1 while True: body = get(path, dict(params, page=page)) rows.extend(body["data"]) if not body["pagination"]["has_more"]: return rows page += 1 time.sleep(0.2) # small pause between requests snps = get_all_pages("/genes/BRCA1/snps") print(len(snps), "SNPs")

This works for every endpoint with page / limit paging (see the endpoint table). For the /download/… endpoints, increase offset by limit instead, until fewer than limit rows come back.

10. How to Use the Interactive Console

The console below is powered by Swagger UI — test any endpoint directly from your browser without writing code.

Before you start: You need an API key. Log in to your profile to generate one instantly — once you have a key, this console authorizes itself whenever you're logged in. Otherwise, click the Authorize button at the top right of the console, paste your key, and click Authorize.

1 Authorize

Automatic when you're logged in with a key. Otherwise click "Authorize" at the top right, paste your X-API-Key, and confirm. The key is remembered in this browser across page reloads.

2 Find an Endpoint

Type in the filter box above the console to narrow the list by tag (e.g. Proteins), then click an endpoint row to expand it.

3 Fill Parameters

Inputs are editable straight away. Required values are marked *; example values are pre-filled to help you get started.

4 Execute

Click "Execute" to fire the request. You'll see the full URL, a ready-to-copy cURL command, status code, response time and JSON response.

Testing in a browser tab? A tab can't send the X-API-Key header, so add your key to the URL instead: …/api/genes/BRCA1?api_key=YOUR_KEY
Tip: Copy the generated cURL command and adapt it for Python (requests), R (httr), or any other language to integrate GeDiPNet data into your pipeline.

11. Citing & Terms of Use

How to cite

If you use data retrieved through the GeDiPNet API in a publication, tool or dataset, please cite:

Kundu I, Sharma M, Barai RS, Pokar K, Idicula-Thomas S (2023). GeDiPNet: Online resource of curated gene-disease associations for polypharmacological targets discovery. Genes & Diseases. https://doi.org/10.1016/j.gendis.2022.05.034

Read the paper

Terms of use

  • Free access: API keys are free. Keep within the rate limits and don't share your key; each person or pipeline should use its own.
  • Third-party data: GeDiPNet integrates records from external resources (e.g. ClinVar, GenCC, GWAS Catalog, PubTator, KEGG, Reactome, UniProt, Pfam, miRTarBase, TRRUST and dbSNP). Those records remain subject to their original providers' licences and terms. Some, such as KEGG, restrict commercial use, so check each source's terms before redistributing or using the data commercially, and cite the original sources where appropriate.
  • Research use: data are provided as-is to support research. They are not intended for clinical diagnosis or treatment decisions.

Contact

For questions about licensing, redistribution, commercial use or higher rate limits, or to report a problem with the API, email gedipnet@bicnirrh.res.in.

Interactive Console

Download OpenAPI spec
Loading console…
Jump to console