Skip to content

Server reference

refgenie serve runs the refgenie server: a REST API for listing, browsing and downloading assets, plus GA4GH DRS and sequence collections endpoints. For a step-by-step setup, see Run a server.

refgenie serve [-p PORT] [-r]
FlagDescription
-p, --portPort to listen on (default 8000). The server listens on all interfaces.
-r, --reloadRestart when the code changes. For development only.

It needs the server extra: pip install "refgenie[server]>=1.0.0a3".

The full list, with request and response formats, is at /docs (Swagger UI) and /redoc on any running server.

PathWhat it serves
/A short landing page with links to the docs
/v4/genomes, /v4/assets, /v4/asset_groups, /v4/asset_classes, /v4/recipes, /v4/aliasesCatalog listings, with pagination and search
/v4/archives/{asset_digest}/downloadAn archive-mode asset as a .tgz
/v4/assets/{asset_digest}/files/{file_path}One file of a file-mode asset
/v4/summary, /v4/species/summaryCounts of genomes, asset groups and assets
/v4/data_channel/The data channels this server re-serves (see Serve data channels)
/ga4gh/drs/v1/GA4GH Data Repository Service objects for staged assets
/seqcolGA4GH sequence collections for the server's genomes
/service-infoWhat this server is and which features it has
/mcpA read-only MCP server for AI assistants
/v4/healthcheckReturns {"status": "ok"}

Downloads redirect to a remote when the asset was pushed to one. See Remotes on a server.

The server reads the same variables as the CLI, plus a few of its own.

VariableDefaultDescription
REFGENIE_HOME_PATH~/.refgenieBase directory for refgenie files
REFGENIE_DB_CONFIG_PATH$REFGENIE_HOME_PATH/refgenie_db_config.yamlDatabase config. Use PostgreSQL for a production server; see Database backends.
REFGENIE_GENOME_FOLDER$REFGENIE_HOME_PATH/genomesWhere asset data lives
REFGENIE_GENOME_STAGE_FOLDER$REFGENIE_HOME_PATH/archivesWhere staged assets live
REFGENIE_LOG_LEVELWARNINGLog verbosity
REFGENIE_PUBLIC_URLhttps://api.refgenie.orgThe server's public base URL, for MCP download links
REFGENIE_COLLECTIONSunsetA JSON list of collection pages for the web UI, each drawn from one or more stores; a collection shows once its stores are served, and an invalid value stops the server at startup. See deployment/collections.example.json.
REFGENIE_CATALOG_URLunsetA publish catalog (made by refgenie catalog-export) to import at startup and then on a schedule. The catalog also lists the RefgetStores the server reads; a change to that list takes effect at the next import, without a restart.
CATALOG_IMPORT_INTERVAL_SECONDS86400How often to re-import REFGENIE_CATALOG_URL
DATA_CHANNELS_CONFIG_PATHthe packaged data_channels.yamlWhich data channels to re-serve
DOWNLOAD_COUNT_DUMP_JOB_INTERVAL_SECONDS60How often download counts are saved
REFGENIE_SERVER_PLUGINSfalseRun plugins on the server

The server counts archive downloads (/v4/archives/{asset_digest}/download) in memory and adds them to the database every DOWNLOAD_COUNT_DUMP_JOB_INTERVAL_SECONDS. The totals appear as download_count in /v4/archives.

A store may carry an optional species.json next to its rgstore.json. The server uses it to show common names and to let users search genomes by any species name.

{"species": [
{"taxon_id": 10116, "scientific_name": "Rattus norvegicus", "common_name": "Norway rat", "synonyms": ["brown rat", "rat"]}
]}
  • taxon_id: NCBI taxon id, an integer, required, unique in the file.
  • scientific_name: required.
  • common_name and synonyms (a list of other names): optional.

refgenie store sync reads the file from every enabled store, local or http(s). A missing file is fine and bad entries are skipped. If a store's file cannot be read, the existing species rows are kept.

Stores are merged in priority order. The scientific name comes from the highest-priority store, the common name is the first non-blank one, and every other name from every store is kept once (ignoring case). Each listed taxon is rewritten, so a name removed from a file disappears. Taxa that no file lists are kept; delete them by hand if needed. A server's catalog import updates species the same way.