references/verified-api.md
Verified release and service contracts
Reviewed 2026-10-01. Tested Python 3.13, GSEApy 1.3.1, gprofiler-official 1.0.0 and MyGene 3.2.2. Native synthetic tests cover local ORA, classic/multilevel prerank, phenotype GSEA, ssGSEA, GSVA and plotting. Small live queries used public example genes only. They establish request/response behavior, not biological validity or population-level FDR calibration.
Enrichr / GSEApy
Released 1.3.1, Python service client, statistics implementation, API reference, provider help.
Base: https://maayanlab.cloud/Enrichr; public routes need no API key.
Human and mouse share this base; fly, yeast, worm and fish route to
FlyEnrichr, YeastEnrichr, WormEnrichr and FishEnrichr respectively.
No pagination is implemented for these catalog, GMT or per-library result routes.
| Use | Request | Response |
|---|---|---|
| Catalog | GET /datasetStatistics | statistics[].libraryName; live native call verified |
| Download library | GET /geneSetLibrary?mode=text&libraryName=... | tab-delimited term, description, genes; live 50-set Hallmark download verified |
| Standard query | POST /addList, multipart list as newline-separated IDs and description | userListId, shortId |
| Standard result used by 1.3.1 | GET /export, userListId, backgroundType, filename | TSV results; columns include Overlap |
| Alternate JSON result | GET /enrich, userListId, backgroundType | object keyed by library, rows as positional arrays |
Explicit online background uses https://maayanlab.cloud/speedrichr/api:
POST /addList with the same multipart fields; POST /addbackground with
form field background (newline-separated genes), returning backgroundid;
POST /backgroundenrich with form fields userListId, backgroundid,
backgroundType. JSON is keyed by library; 1.3.1 expects each row as rank,
term, p, odds ratio, combined score, gene list, adjusted p, legacy p, legacy
adjusted p. Its parsed DataFrame has no Overlap column.
Standard and Speedrichr submission/export contracts were exercised through the actual installed SDK with mocked HTTP responses, not live list uploads. Nonhuman custom-background routing was not validated; use pinned local GMTs. Service rate limits/timeouts and annotation changes remain operational concerns; 1.3.1 lacks finite timeouts on several calls. A stalled request is not an empty scientific result. Preserve raw results, query/background and library snapshots.
Two release/documentation mismatches were resolved against released code/runtime:
- Online iterable backgrounds do select Speedrichr despite the public wrapper docstring saying they are ignored.
- Classic GSEA FDR groups by term prefix before
__; multilevel uses global BH. Extreme native classic prerank sets returned nominal zero p-values despite release notes mentioning a floor. Preserve reported values and describe their finite permutation resolution; do not claim exact zero probability.
g:Profiler
Official API documentation, method/domain documentation, official Python package. The API page was read directly as server-rendered HTML when web extraction timed out.
Base https://biit.cs.ut.ee/gprofiler; no authentication for these query routes.
JSON POSTs return result and meta; no pagination parameters are documented
for these analysis/mapping calls. all_results controls significance filtering,
not paging. The client has no timeout parameter.
/api/gost/profile/:organism,query,sources,background,domain_scope,ordered,all_results,no_evidences,significance_threshold_method,user_threshold,numeric_ns, etc.p_valueis adjusted. LiveREACquery for TP53/BRCA1/BRCA2 returned matching genes, per-source domain sizes and metadata.no_evidences=Falserequests intersections; default True omits them. Save.metabefore another call./api/convert/convert/:organism,query,target,numeric_ns. Live Ensembl TP53 conversion toENTREZGENE_ACCreturned7157; the legacyENTREZGENEtarget returnedTP53. Check namespace, not merely nonempty output./api/orth/orth/:organism,targetspecies,query,numeric_ns, optionalaresolve. Live mouse Trp53 → human returned targetortholog_ensg=ENSG00000141510. Sourceconvertedis distinct from target ID.
Python 1.0.0 omits a trailing slash on mapping URLs (accepted live). It overwrites
any supplied domain_scope with custom if background is not None, so do not
claim its wrapper implements custom_annotated. Mapping can be ambiguous or fail;
query and assay universe must undergo the same mapping policy.
MSigDB
Official releases/collections, human collections, mouse collections, GSEApy downloader source.
Current human/mouse release: 2026.1.Hs / 2026.1.Mm. GSEApy does unauthenticated
GETs at https://data.broadinstitute.org/gsea-msigdb/msigdb/release/, then the
release directory and {category}.v{dbver}.{symbols|entrez}.gmt. Directory
HTML parsing requires lxml; there is no result pagination. Live listing,
human categories and 50-set h.all download succeeded. The website requests
registration and license compliance independently of public file availability.
Mouse category and namespace must both match its own release. Neither a year
in an Enrichr library name nor a successful download proves current gene mapping.
Identifier services
BioMart REST/XML documentation, GSEApy BioMart source, MyGene query API, MyGene Python client.
BioMart uses public /biomart/martservice: metadata GETs for registry, datasets,
attributes and filters, then XML query via GET query or POST form query.
It returns an attribute-ordered tabular stream, not paginated JSON. GSEApy batches
long identifier filters. The default-host live query yielded service-unavailable
HTML that the SDK accepted as a one-column DataFrame. Validate expected columns
and identifiers; this observation does not establish retirement. A successful
live BioMart mapping was not obtained.
MyGene querymany uses public POST https://mygene.info/v3/query with q,
scopes, fields, species; batching is handled by the client. Its list response
has query plus matching fields or notfound; one input can yield multiple rows.
returnall=True adds client diagnostics dup and missing. A live single-ID
query returned TP53/7157. The separate GET search uses size/from or
fetch_all/scroll_id; these search pagination controls are not querymany batch
identifiers. Querying human with a mouse symbol is not orthology mapping.
Scientific interpretation and adjacent APIs
GSEA User Guide, GSEA FAQ, decoupler PROGENy reference.
GSEA size filters use genes intersecting the rank. Class-label permutations
require exchangeability; gene-set permutations change the null and lose gene
correlations. Enrichment sign is rank direction, not proof of pathway activation.
Decoupler is a documentation-only pointer here; no decoupler model downloads or
activity-inference runs were made. Reactome/KEGG/STRING raw APIs remain delegated
to database-lookup; this skill does not invent duplicate endpoint examples.