Docs / Genome Source Releases API

Genome Source Releases API

What release each upstream genome data source is on, and when we last managed to read it. Four sources today — RefSeq, dbSNP, 1000 Genomes/IGSR and NCBI Datasets — each probed once a day and read from the source itself rather than hardcoded. Release markers only: no sequence, no assembly, no annotation and no variant data is served here or held behind it. Every row carries the probe's own verdict next to the version, because a version number alone cannot tell a release that has not moved from a probe that has stopped working — IGSR's newest data freeze really is from 2013, and dbSNP's marker used to be read off a single variant record, which is a number that can freeze without anything saying so.

Live https://api.softon.dev/v1 v1 · stable

Endpoints

Endpoint	Route	Returns
List source releases	`GET /v1/genome/releases`	collection
Retrieve a source release	`GET /v1/genome/releases/{id}`	single object

The Genome object

The fields below appear on the dataset's primary resource. Endpoint pages list any fields specific to them.

Field	Type	Description
`id`	string	The upstream registry's own key — `refseq`, `dbsnp`, `igsr_1000g`, `ncbi_datasets`. The one id on this API with no `<source>:` prefix, because the row's identity IS an upstream source; it is the same string as `source_id` and it is what `/v1/genome/releases/{id}` takes.
`source`	string	Which softon scraper delivered this row. One probe pass reads every source here, so it is the same value on every row — `source_id` is the field that varies, and the one you almost certainly mean.
`source_id`	string	The upstream registry's key, identical to `id`. Published under this name because it is the name the registry this replaces uses, so a consumer writing softon's answer back into that registry keys on it without a mapper.
`source_name`	string	What the source calls itself: `RefSeq`, `dbSNP`, `1000 Genomes / IGSR`, `NCBI Datasets`.
`authority`	string	The body that publishes it — `NCBI` or `EMBL-EBI`.
`category`	string	The registry's own label for what kind of source this is: `reference_sequence`, `genome_metadata`, `variation`, `population_reference`. A shared free-form vocabulary rather than a closed set, so `?category=` accepts anything and answers an empty page for a label no source carries.
`landing_url`	string · nullable	The human-facing page for this source. Never the FTP index — this is the one to link a reader to.
`api_url`	string · nullable	The source's machine-facing API root, where it has one. Null for RefSeq and IGSR, which have none.
`bulk_url`	string · nullable	The source's bulk archive root, where it has one. Null for NCBI Datasets. Recorded, never mirrored: nothing on this platform downloads it, and this API serves no data from behind it.
`update_frequency`	string	How often the SOURCE cuts a release — `periodic_release`, `release_based`, `continuous`. Not how often softon probes it: the probe runs daily whatever this says.
`release_version`	string · nullable	The release the source is currently on, as a string and never a number: `"237"`, `"18.37.0"`, `"157"`, `"20130502"`. Release names are not all numeric and a JSON number would also defeat a `?? "—"` null check the day one of them is `0`. This is a release MARKER and nothing else. It pins no download, selects no file and carries no sequence, assembly, annotation or variant data — for RefSeq, for instance, assembly facts come from the separate ASSEMBLY_REPORTS bulk tables and not from anything here. Null until a probe has succeeded once. After that it is sticky: a probe that fails leaves the last good value standing and moves `status` instead, so read the two together rather than treating a non-null version as fresh.
`release_date`	date · nullable	The release's own date where the source publishes one. Today only `igsr_1000g` has it, and there it is the freeze name sliced out of a directory name (`20130502` → `2013-05-02`) — an identity, not a publication date. Deliberately not filled from an upstream `Last-Modified`, which is a different fact.
`checksum`	string · nullable	The version signal for sources identified by a digest rather than a number. Null on every source served today.
`format`	string · nullable	How the UPSTREAM distributes its data — `flatfile`, `rest_v2`, `ftp_release_dirs`, `text_release_notes`. Not the format of this response, which is JSON for all of them.
`retrieved_at`	timestamp · nullable	When softon last successfully read this upstream. Not when your request arrived, and never advanced by a probe that failed — it is a provenance claim, and a failed refresh that moved it would assert a read that did not happen. Compare it with `ingested_at`, which is the last probe of any kind, to see how stale the answer is. Null only for a source that has never answered.
`status`	string	How the LATEST probe went. Four values, and they are four because the distinctions matter to different people: `ok` — a release was read. `degraded` — the host answered 2xx and nothing parseable came back, so the upstream's format moved and a person has to fix the probe. `unreachable` — the host never answered: DNS, TLS, connection or timeout. Nothing is wrong with softon's parser and nothing is wrong with the data. `error` — the host answered with a non-2xx. The feed this replaces collapsed `unreachable` into `degraded` and then counted the source as reachable anyway, so an outage read as a parser bug.
`extra`	object · nullable	Per-source probe metadata: which URL was read, what it answered, and the handful of fields the upstream published beside the version. An allow-listed projection, not the upstream body — one of these endpoints echoes a submitted API key back inside its own error body, so a verbatim pass-through would publish a credential. Null where a source records none.
`sort_order`	integer	This source's position in the upstream registry's declaration order, 1–10. Sort on it to reproduce that order: this collection pages on `ingested_at` like every other one here, and one probe pass stores every row at the same instant, so the order rows come back in is the id's and not the registry's.
`ingested_at`	timestamp	When the latest probe ran and this version was stored — successful or not. See `retrieved_at` for the last successful read.