{"openapi":"3.1.0","info":{"title":"GenPhenia API","version":"0.21.1","summary":"Rank candidate genes from HPO terms and get the next phenotype questions to ask.","description":"GenPhenia ranks the genes most likely to explain a patient's rare disease from their phenotype, written as Human Phenotype Ontology (HPO) terms, and suggests which findings to check next. GenPhenia is a research tool: its rankings are not a diagnosis. Send HPO terms only, never names, dates or record numbers. Human-readable reference: https://genphenia.com/docs/api.","termsOfService":"https://genphenia.com/terms","contact":{"name":"GenPhenia","email":"gianlucisnt@gmail.com","url":"https://genphenia.com/docs/api"}},"servers":[{"url":"https://genphenia.com"}],"externalDocs":{"description":"API reference","url":"https://genphenia.com/docs/api"},"paths":{"/api/gene-ranking":{"post":{"operationId":"rankGenes","summary":"Rank genes for a set of HPO terms","description":"Ranks every gene GenPhenia knows for the findings present and returns the top topK. Needs an API token. Each token may start one ranking or export per second.","security":[{"bearerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneRankingRequest"},"example":{"observedIds":["HP:0001250","HP:0001263"],"topK":20}}}},"responses":{"200":{"description":"The ranking.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneRankingResponse"}}}},"400":{"description":"The body is not valid, or none of the terms are in the model's HPO release (ignoredHpoIds lists them).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankingInputError"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls from this token, or GenPhenia is busy. Wait Retry-After seconds and try again.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The analysis failed; quote reference when you report it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The analysis took longer than 30 seconds and was stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/gene-ranking/export":{"post":{"operationId":"exportGeneRanking","summary":"Export a ranking as TSV or PDF","description":"kind \"tsv\" returns the whole ranking as a tab-separated file; \"pdf\" returns a report on the top 15 genes. Needs an API token.","security":[{"bearerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequest"},"example":{"observedIds":["HP:0001250","HP:0001263"],"kind":"tsv"}}}},"responses":{"200":{"description":"The file, sent as an attachment.","content":{"text/tab-separated-values":{"schema":{"type":"string"}},"application/pdf":{"schema":{"type":"string","contentMediaType":"application/pdf"}}}},"400":{"description":"The body is not valid, or none of the terms are in the model's HPO release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls from this token, or GenPhenia is busy. Wait Retry-After seconds and try again.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The export failed; quote reference when you report it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The export took longer than 30 seconds and was stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/diagnoser":{"post":{"operationId":"suggestNextPhenotypes","summary":"Suggest the next findings to check","description":"Scores candidate HPO terms by how much their answer would narrow the possible diseases (information gain) and returns the best ones, with the diseases that fit best so far. No token needed.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnoserRequest"},"example":{"observedIds":["HP:0001250"],"answers":[{"hpoId":"HP:0001263","value":"no"}],"topQuestions":4,"topDiseases":5}}}},"responses":{"200":{"description":"Next questions and best-fitting diseases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnoserResponse"}}}},"400":{"description":"The body is not valid, or an HPO ID is outside GenPhenia's release (unknownHpoIds lists it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnoserInputError"}}}},"429":{"description":"Too many calls from this token, or GenPhenia is busy. Wait Retry-After seconds and try again.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The analysis failed; quote reference when you report it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The analysis took longer than 30 seconds and was stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","description":"A GenPhenia API token. To ask for one, write to gianlucisnt@gmail.com with your name, institution and what you plan to run."}},"headers":{"RetryAfter":{"description":"Seconds to wait before trying again.","schema":{"type":"integer","minimum":1}}},"schemas":{"HpoId":{"type":"string","pattern":"^HP:\\d{7}$","description":"An HPO term ID: HP: and seven digits.","examples":["HP:0001250"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong, in one sentence."},"reference":{"type":"string","description":"Present when an analysis failed; quote it when you report the failure."}}},"RankingInputError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"ignoredHpoIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"}}}}]},"DiagnoserInputError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"unknownHpoIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"}}}}]},"GeneRankingRequest":{"type":"object","required":["observedIds"],"properties":{"observedIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"},"minItems":1,"maxItems":128,"description":"The findings present, as HPO IDs. Malformed IDs are dropped; terms the model's HPO release does not know are left out of the ranking and listed in meta.ignoredHpoIds."},"topK":{"type":"integer","minimum":1,"maximum":200,"default":20,"description":"How many genes to return. Larger values are clamped to 200."}}},"ExportRequest":{"type":"object","required":["observedIds","kind"],"properties":{"observedIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"},"minItems":1,"maxItems":128,"description":"The findings present, as HPO IDs. Malformed IDs are dropped; terms the model's HPO release does not know are left out of the ranking and listed in meta.ignoredHpoIds."},"kind":{"type":"string","enum":["tsv","pdf"]}}},"RankedGene":{"type":"object","required":["rank","gene","probability"],"properties":{"rank":{"type":"integer","minimum":1},"gene":{"type":"string","description":"HGNC gene symbol."},"probability":{"type":"number"},"cumulativeProbability":{"type":"number"},"associatedLabels":{"type":"array","items":{"type":"string"},"description":"Up to five disease or context labels linked to the gene."},"evidence":{"type":"object","description":"ClinGen gene-disease validity curations for the gene.","properties":{"label":{"type":["string","null"],"description":"The strongest classification."},"recordCount":{"type":"integer"},"topDisease":{"type":"string"}},"additionalProperties":true},"actionability":{"type":"object","description":"ClinGen actionability curations for the gene, adult and pediatric.","properties":{"label":{"type":["string","null"]},"recordCount":{"type":"integer"},"topContext":{"type":"string"}},"additionalProperties":true}}},"GeneRankingResponse":{"type":"object","required":["meta","summary","topGenes"],"properties":{"meta":{"type":"object","properties":{"modelVersion":{"type":"string","description":"Record it with your results."},"activeCheckpointId":{"type":"string"},"inputHpoIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"},"description":"The terms ranked."},"expandedHpoIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"},"description":"The terms the model scored, including ancestors of the input."},"ignoredHpoIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"},"description":"Requested terms left out because the model's HPO release does not know them."}},"additionalProperties":true},"summary":{"type":"object","properties":{"fullRankingSize":{"type":"integer","description":"Genes in the full ranking."},"topProbabilityMass":{"type":"number","description":"Probability summed over topGenes."},"maxProbability":{"type":"number"},"genesWithEvidence":{"type":"integer"},"genesWithActionability":{"type":"integer"}}},"topGenes":{"type":"array","items":{"$ref":"#/components/schemas/RankedGene"}}}},"Answer":{"type":"object","required":["hpoId","value"],"properties":{"hpoId":{"$ref":"#/components/schemas/HpoId"},"value":{"type":"string","enum":["yes","no","unknown"]}}},"DiagnoserRequest":{"type":"object","properties":{"observedIds":{"type":"array","items":{"$ref":"#/components/schemas/HpoId"},"maxItems":128,"description":"The findings present, as HPO IDs."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/Answer"},"maxItems":128,"description":"Findings already asked about. Include unknown answers too, or the same questions come back."},"topQuestions":{"type":"integer","minimum":1,"maximum":8,"default":4},"topDiseases":{"type":"integer","minimum":1,"maximum":10,"default":5}}},"DiagnoserResponse":{"type":"object","properties":{"summary":{"type":"object","description":"How many diseases are still compatible, the remaining uncertainty and answer counts.","additionalProperties":true},"top_questions":{"type":"array","items":{"type":"object","properties":{"hpo_id":{"$ref":"#/components/schemas/HpoId"},"label":{"type":"string"},"information_gain_bits":{"type":"number"},"p_yes":{"type":"number"},"p_no":{"type":"number"}},"additionalProperties":true}},"top_diseases":{"type":"array","items":{"type":"object","properties":{"disease_id":{"type":"string"},"disease_name":{"type":"string"},"posterior":{"type":"number"}},"additionalProperties":true}}},"additionalProperties":true}}}}