API
GenPhenia API
Rank candidate genes from HPO terms and get the next questions to ask, over HTTPS with JSON.
The base address is https://genphenia.com. Requests and responses are JSON, except exports, which return a file. The same calls are described for OpenAPI tools at /openapi.json.
Access
- Next questions (
POST /api/diagnoser) is open: no account or token. - Gene ranking and exports need an API token, sent as
Authorization: Bearer <token>. To ask for one, write to [email protected] with your name, your institution and what you plan to run. - Keep the token out of addresses, logs and shared code. Anyone who has it can run analyses as you.
Limits
- Each token can start one ranking or export per second.
- GenPhenia runs a few analyses at a time for everyone. When it is busy, a call waits up to 20 seconds, then gets
429with aRetry-Afterheader. Wait that many seconds and try again. - A single analysis is stopped after 30 seconds.
- For batches of hundreds of cases, send them one at a time, and tell us first.
Errors
Errors return JSON with an error sentence. Failed runs also carry a reference; quote it if you write to us.
| Status | Meaning |
|---|---|
| 400 | The body is not valid; error says why |
| 401 | Missing or invalid token |
| 429 | Too many calls, or GenPhenia is busy; wait Retry-After seconds |
| 500 | The analysis failed |
| 504 | The analysis took longer than 30 seconds and was stopped |
Rank genes
POST /api/gene-ranking ranks every gene GenPhenia knows for a set of HPO terms and returns the top of the list.
curl -s https://genphenia.com/api/gene-ranking \
-H "Authorization: Bearer $GENPHENIA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"observedIds": ["HP:0001250", "HP:0001263"], "topK": 20}'observedIds: the findings present, as HPO IDs (HP:and seven digits), up to 128. Only these terms affect the ranking. Malformed IDs are dropped.topK: how many genes to return, 20 by default and at most 200.
GenPhenia's model was trained on an HPO release that is a little older than the newest one. Terms it does not know are left out of the ranking and listed in meta.ignoredHpoIds; if none of the terms remain, the call returns 400.
The response has three parts:
topGenes: one entry per gene, withrank,gene,probability,cumulativeProbability, the phenotype labels linked to the gene (associatedLabels), its ClinGen gene–disease validity records (evidence) and ClinGen actionability (actionability).meta:modelVersion,inputHpoIds(the terms ranked),ignoredHpoIdsand the model checkpoint. Record the model version with your results.summary: the size of the full ranking and how much probability the returned genes hold.
Export a ranking
POST /api/gene-ranking/export takes the same observedIds and a kind: "tsv" returns the whole ranking as a tab-separated file, "pdf" a report on the top 15 genes.
curl -s https://genphenia.com/api/gene-ranking/export \
-H "Authorization: Bearer $GENPHENIA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"observedIds": ["HP:0001250", "HP:0001263"], "kind": "tsv"}' \
-o genphenia-full-ranking.tsvNext questions
POST /api/diagnoser suggests which findings to check next. It scores each candidate HPO term by how much its answer would narrow the list of possible diseases (information gain) and returns the best ones, with the diseases that fit best so far.
curl -s https://genphenia.com/api/diagnoser \
-H "Content-Type: application/json" \
-d '{"observedIds": ["HP:0001250", "HP:0001263"], "topQuestions": 4, "topDiseases": 5}'observedIds: the findings present, as HPO IDs.answers: findings already asked about, as{"hpoId": "HP:0001263", "value": "no"}, wherevalueisyes,noorunknown. Sendunknownanswers too, or the same questions come back.topQuestions: up to 8, 4 by default.topDiseases: up to 10, 5 by default.
The response lists top_questions (hpo_id, label, information_gain_bits, p_yes, p_no), top_diseases (disease_id, disease_name, posterior) and a summary with the number of diseases still compatible. An HPO ID outside GenPhenia's release returns 400 with unknownHpoIds.
What GenPhenia records
API calls are recorded like website use: the HPO terms and answers, and for rankings the top 20 genes and the model version, with the name of the token that made the call. Send HPO terms only, never names, dates or record numbers.
Hand a case to the website
To give a researcher a case to explore on genphenia.com instead, build a link with the terms after #terms=, separated by commas: https://genphenia.com/#terms=HP:0001250,HP:0001263. See AI assistants.