{"openapi":"3.1.0","info":{"title":"taxon-sync API","version":"1","description":"Reconcile bacterial/archaeal taxon names across NCBI, GTDB, SILVA, Greengenes2 and eHOMD. Every name traces to an official release file — nothing is invented. /api/translate (unversioned) is a legacy alias of /api/v1/translate.","license":{"name":"MIT"}},"servers":[{"url":"https://taxon-sync.vercel.app","description":"production"}],"paths":{"/api/v1/translate":{"get":{"summary":"Translate one or more taxon queries","description":"A query is a name (e.g. 'Bacteroides vulgatus') or an NCBI taxid (e.g. 821). For multiple queries, repeat ?input= or newline-separate them. NB ';', '>' and '|' are LINEAGE separators within a single query (it collapses to the deepest filled segment, skipping empty ranks and strain ids) — they do NOT split into multiple queries. Capped at 2000 queries — inputs beyond the cap are discarded, and count.truncated reports how many.","parameters":[{"name":"input","in":"query","required":true,"description":"A taxon name or NCBI taxid. Repeat for multiple queries.","schema":{"type":"array","items":{"type":"string"}},"example":"Bacteroides vulgatus"},{"name":"gtdb","in":"query","required":false,"description":"GTDB release to translate against. Defaults to the current release. See GET /api/v1/versions for the list. Unknown value -> 400.","schema":{"type":"string"},"example":"R226"},{"name":"silva","in":"query","required":false,"description":"SILVA release. Defaults to current. See /api/v1/versions.","schema":{"type":"string"}},{"name":"gg2","in":"query","required":false,"description":"Greengenes2 release. Defaults to current. See /api/v1/versions.","schema":{"type":"string"}},{"name":"ehomd","in":"query","required":false,"description":"eHOMD release. Defaults to current. See /api/v1/versions.","schema":{"type":"string"}},{"name":"idSpace","in":"query","required":false,"description":"How a bare number is read: 'ncbi' (default) as an NCBI taxid, 'ehomd' as an eHOMD HMT id ('389' is HMT-389), bound through eHOMD's own NCBI Taxon ID column and matched as matchType 'ehomd'. A number the chosen space lacks is matchType 'none', never re-read as an NCBI taxid. Names are unaffected. Greengenes2 is not offered: its integer ids are sequence features, millions per release. Unknown value -> 400.","schema":{"type":"string","enum":["ncbi","ehomd"],"default":"ncbi"}}],"responses":{"200":{"description":"Translation result. `releases` echoes the resolved versions used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateResult"}}}},"400":{"description":"Empty input, an unknown release or an unknown idSpace (message lists the valid ones).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"Translate a batch of queries","description":"Send many queries in the body: JSON { \"input\": \"line1\\nline2\" } or a raw text/plain body with one query per line. Capped at 2000 lines — lines beyond the cap are discarded, and count.truncated reports how many.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string"},"idSpace":{"type":"string","enum":["ncbi","ehomd"],"default":"ncbi","description":"How a bare number is read: 'ncbi' (default) as an NCBI taxid, 'ehomd' as an eHOMD HMT id ('389' is HMT-389), bound through eHOMD's own NCBI Taxon ID column and matched as matchType 'ehomd'. A number the chosen space lacks is matchType 'none', never re-read as an NCBI taxid. Names are unaffected. Greengenes2 is not offered: its integer ids are sequence features, millions per release. Unknown value -> 400."},"versions":{"type":"object","description":"Optional per-db release selection; omitted dbs use the current default.","properties":{"gtdb":{"type":"string"},"silva":{"type":"string"},"gg2":{"type":"string"},"ehomd":{"type":"string"}}}},"required":["input"]},"example":{"input":"821\nEscherichia coli","versions":{"gtdb":"R226"}}},"text/plain":{"schema":{"type":"string"},"example":"821\nEscherichia coli"}}},"responses":{"200":{"description":"Translation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateResult"}}}},"400":{"description":"Empty input, or an unknown release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/taxon":{"get":{"summary":"Everything every held release says about one taxon","description":"Single-taxon view — the data behind the /t/<taxid> pages. Provide taxid OR name (names resolve through the same lookup as /translate, so redirects, deleted taxids and GTDB suffixes behave identically). Optional gtdb/silva/gg2/ehomd params restrict the per-release cells to those releases; by default every held release is returned.","parameters":[{"name":"taxid","in":"query","required":false,"description":"NCBI taxid. One of taxid or name is required.","schema":{"type":"string"},"example":"821"},{"name":"name","in":"query","required":false,"description":"A taxon name, resolved to a taxid via the translator's lookup. One of taxid or name is required.","schema":{"type":"string"},"example":"Bacteroides vulgatus"},{"name":"gtdb","in":"query","required":false,"description":"Restrict GTDB cells to this release. See /api/v1/versions. Unknown value -> 400.","schema":{"type":"string"},"example":"R226"},{"name":"silva","in":"query","required":false,"description":"Restrict SILVA cells to this release.","schema":{"type":"string"}},{"name":"gg2","in":"query","required":false,"description":"Restrict Greengenes2 cells to this release.","schema":{"type":"string"}},{"name":"ehomd","in":"query","required":false,"description":"Restrict eHOMD cells to this release.","schema":{"type":"string"}}],"responses":{"200":{"description":"The taxon across every (or each requested) release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxonView"}}}},"400":{"description":"Neither taxid nor name given, or an unknown release (message lists the valid ones).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"No match for the name, or an unknown taxid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/versions":{"get":{"summary":"List available database releases + current defaults","description":"Discovery endpoint for version pickers — the releases each database offers and which is the default. Use these release strings as the gtdb/silva/gg2 params on /translate.","responses":{"200":{"description":"Available versions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Versions"}}}}}}},"/api/v1/health":{"get":{"summary":"Readiness probe + the data snapshot being served","description":"Answers from the release manifest alone, without loading any data pack, so it is cheap to poll. Never cached. releases lists every held release per database, in chronological order.","responses":{"200":{"description":"The server is up and has its manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"The release manifest could not be read. The body is JSON with the CORS header, so a browser dashboard can show it.","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","ok","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"ok":{"type":"boolean","const":false},"error":{"type":"string"}}}}}}}}},"/api/v1/dataset":{"get":{"summary":"Download the entire mapping table as TSV","description":"The whole cross-database table as one tab-separated file — every taxon we hold, one row each (~97,000 rows, ~10MB). Streamed, and cached hard at the edge: the body is a pure function of the resolved releases, which name immutable source files. Use this instead of looping /translate. Columns: ncbi_taxid, ncbi_name, then one per database named for its release (gtdb_R232, silva_138.2, gg2_2024.09, ehomd_4.2), each followed by _status and _split_count where that database carries them (SILVA does not). Split lineages are written out in full ('A / B / C'), never summarised as '(+n)'. Cells are sanitised: tabs/newlines flattened to spaces, and a leading =, +, - or @ is prefixed with an apostrophe so spreadsheets read the value as text. Licence: the sources are open; attribute NCBI Taxonomy, GTDB, SILVA, Greengenes2 and eHOMD on publication, citing the releases in the header row.","parameters":[{"name":"gtdb","in":"query","required":false,"description":"GTDB release to dump. Defaults to the current release. See GET /api/v1/versions. Unknown value -> 400.","schema":{"type":"string"},"example":"R226"},{"name":"silva","in":"query","required":false,"description":"SILVA release. Defaults to current.","schema":{"type":"string"}},{"name":"gg2","in":"query","required":false,"description":"Greengenes2 release. Defaults to current.","schema":{"type":"string"}},{"name":"ehomd","in":"query","required":false,"description":"eHOMD release. Defaults to current.","schema":{"type":"string"}}],"responses":{"200":{"description":"The full table. Content-Disposition names the resolved releases, so a downloaded file is self-identifying; x-row-count gives the number of DATA rows (the header line is not counted).","headers":{"Content-Disposition":{"description":"attachment; filename=\"taxon-sync-gtdb-<rel>_silva-<rel>_gg2-<rel>_ehomd-<rel>.tsv\"","schema":{"type":"string"}},"x-row-count":{"description":"Number of data rows, excluding the header line.","schema":{"type":"integer"}}},"content":{"text/tab-separated-values":{"schema":{"type":"string"},"example":"ncbi_taxid\tncbi_name\tgtdb_R232\tgtdb_R232_status\tgtdb_R232_split_count\tsilva_138.2\t…\n7\tAzorhizobium caulinodans\tAzorhizobium caulinodans\tcurrent\t\tAzorhizobium caulinodans\t…"}}},"400":{"description":"Unknown release (message lists the valid ones).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/diff":{"get":{"summary":"Diff one database between two of its releases","description":"What changed for a database across two releases: a summary (shared / renamed / unchanged / gained / lost) plus the renamed list (capped at 500).","parameters":[{"name":"db","in":"query","required":true,"schema":{"type":"string","enum":["gtdb","silva","gg2","ehomd"]}},{"name":"from","in":"query","required":true,"schema":{"type":"string"},"example":"R220"},{"name":"to","in":"query","required":true,"schema":{"type":"string"},"example":"R226"}],"responses":{"200":{"description":"Release diff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDiff"}}}},"400":{"description":"Missing params or unknown db/release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"TranslateResult":{"type":"object","required":["apiVersion","releases","count","rows"],"properties":{"apiVersion":{"type":"string","const":"1"},"releases":{"$ref":"#/components/schemas/Releases"},"count":{"$ref":"#/components/schemas/Count"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/Taxon"}}}},"Releases":{"type":"object","description":"The release each database column is derived from. Pin against these.","properties":{"ncbi":{"type":"string","example":"NCBI Taxonomy taxdump · 2026-10-23"},"gtdb":{"type":"string","example":"GTDB R232"},"silva":{"type":"string","example":"SILVA 138.2"},"gg2":{"type":"string","example":"Greengenes2 2024.09"},"ehomd":{"type":"string","example":"eHOMD 4.2"}}},"Count":{"type":"object","properties":{"total":{"type":"integer"},"matched":{"type":"integer"},"gtdb":{"type":"integer"},"silva":{"type":"integer"},"gg2":{"type":"integer"},"ehomd":{"type":"integer"},"splits":{"type":"integer"},"redirected":{"type":"integer"},"reverseLookups":{"type":"integer"},"deleted":{"type":"integer"},"closest":{"type":"integer"},"drift":{"type":"integer","description":"Rows carrying a precomputed cross-release drift hint (see rows[].drift)."},"truncated":{"type":"integer","description":"Input lines dropped by the 2000-line cap (0 = none dropped)."},"ambiguous":{"type":"integer","description":"Rows whose binomial names two or more NCBI taxa (see rows[].candidates); they stay unmatched."}}},"Taxon":{"type":"object","required":["input","normalised","matchType"],"properties":{"input":{"type":"string","description":"The query as sent."},"normalised":{"type":"string","description":"The query after normalisation."},"matchType":{"type":"string","enum":["taxid","ncbi","gtdb","silva","gg2","ehomd","redirected","deleted","none"],"description":"How (or whether) the query resolved."},"taxid":{"type":"string","description":"Resolved NCBI taxid, when matched."},"row":{"$ref":"#/components/schemas/MappingRow"},"redirectedFrom":{"type":"string","description":"Set when a retired taxid was followed."},"hmt":{"type":"string","description":"Set when a bare number was read with idSpace=ehomd: the eHOMD HMT it named, in eHOMD's spelling ('HMT-058'). Several HMTs can share one species, so the eHOMD cell may show a sibling HMT's name; this is the one asked for.","example":"HMT-389"},"deletedTaxid":{"type":"boolean","description":"Set when the input taxid was deleted by NCBI without replacement."},"droppedSuffix":{"type":"string","description":"Set when a GTDB-style '_A' suffix was stripped to match."},"genusHint":{"$ref":"#/components/schemas/GenusHint"},"suggestions":{"type":"array","description":"Fuzzy candidates, only populated on no-match.","items":{"$ref":"#/components/schemas/Suggestion"}},"closest":{"type":"array","description":"Approximate cross-DB fills for columns the mapping left empty. Not authoritative.","items":{"$ref":"#/components/schemas/Closest"}},"candidates":{"type":"array","description":"Present when the query binomial names two or more NCBI taxa at the same name class. No taxid was chosen: matchType stays none and no cell is filled. Each entry is a taxon it could mean, with its current scientific name; re-submit the taxid you mean. A longer organism name that a database lists verbatim (e.g. a strain name) still resolves as a record match, because it names one record rather than a binomial.","items":{"$ref":"#/components/schemas/Candidate"}},"nameClass":{"type":"string","enum":["current","synonym","equivalent"],"description":"For matchType=ncbi: which class of NCBI name the query hit, in the same words as /taxon's knownAs[].class. A synonym or equivalent-name match is an alias lookup, a weaker identity claim than the current scientific name. Omitted when the class could not be established from the stored names."},"via":{"type":"object","description":"Per database (gtdb, silva, gg2, ehomd): how the selected release's record was joined to the NCBI taxon; see JoinVia. Present for every filled cell except one whose route this API version does not recognise (that cell carries neither via nor absent). Omitted when empty or when the query did not resolve.","additionalProperties":{"$ref":"#/components/schemas/JoinVia"}},"absent":{"type":"object","description":"Per database: why the selected release has no record. Present for every empty cell on a resolved row; omitted when no cell is empty. See Absence.","additionalProperties":{"$ref":"#/components/schemas/Absence"}},"drift":{"type":"array","description":"Databases that changed their mind about this taxon across the releases we hold — INCLUDING releases this request did not select. For kind=renamed, releases[] lists the releases that hold a name (they do not all agree); for kind=absent, releases[] lists the releases holding NO record. Precomputed at pack-build time; omitted when the taxon is stable everywhere. Use GET /api/v1/taxon or /api/v1/diff to see the differing names themselves.","items":{"$ref":"#/components/schemas/Drift"}}}},"MappingRow":{"type":"object","description":"Confirmed cross-database names. Split lineages appear as 'A / B / C (+n)'.","properties":{"ncbi":{"type":"string"},"gtdb":{"type":"string"},"gtdbStatus":{"type":"string","enum":["current","split"]},"gtdbSplitCount":{"type":"integer"},"silva":{"type":"string"},"gg2":{"type":"string"},"gg2Status":{"type":"string","enum":["current","split"]},"gg2SplitCount":{"type":"integer"},"ehomd":{"type":"string"},"ehomdStatus":{"type":"string","enum":["current","split"]},"ehomdSplitCount":{"type":"integer"}}},"Closest":{"type":"object","description":"The nearest record a database actually holds for the resolved organism (by genus + epithet). Approximate — verify via its taxid.","properties":{"db":{"type":"string","enum":["gtdb","silva","gg2"]},"name":{"type":"string"},"taxid":{"type":"string"},"rank":{"type":"string","enum":["species","genus"]},"distance":{"type":"integer"},"genusCount":{"type":"integer"}}},"Drift":{"type":"object","description":"One database's verdict on the taxon across every release of it we hold. 'renamed' and 'absent' are distinct events, not degrees of one. One verdict per database: a taxon some release dropped AND whose name moved between the releases holding it reports 'absent', with the rename in alsoRenamed.","properties":{"db":{"type":"string","enum":["gtdb","silva","gg2","ehomd"]},"kind":{"type":"string","enum":["renamed","absent"],"description":"renamed = the releases that hold it do not agree on the name; absent = some releases have no record at all."},"releases":{"type":"array","items":{"type":"string"},"description":"For 'renamed', the releases holding a name (chronological). For 'absent', the releases with no record."},"alsoRenamed":{"type":"array","items":{"type":"string"},"description":"Only on an 'absent' verdict, and only when the releases that hold the taxon also disagree on its name: those releases (chronological). Omitted otherwise."}}},"GenusHint":{"type":"object","description":"Set when the input resolved only to a known genus (not a species). `count` is the number of distinct species we hold in that genus.","properties":{"genus":{"type":"string"},"source":{"type":"string","enum":["NCBI","GTDB"]},"count":{"type":"integer"}}},"Candidate":{"type":"object","description":"One of the NCBI taxa a contested binomial could mean.","required":["taxid","name"],"properties":{"taxid":{"type":"string"},"name":{"type":"string","description":"The taxon's current NCBI scientific name."}}},"Suggestion":{"type":"object","description":"A fuzzy candidate for a no-match query.","properties":{"name":{"type":"string"},"taxid":{"type":"string"},"ncbi":{"type":"string"},"distance":{"type":"integer","description":"Edit distance from the query."}}},"TaxonView":{"type":"object","description":"One taxon across every held release (from GET /api/v1/taxon). Same assembly that server-renders the /t/<taxid> pages.","required":["apiVersion","taxid","sciName","knownAs","cells","defaults"],"properties":{"apiVersion":{"type":"string","const":"1"},"taxid":{"type":"string"},"sciName":{"type":"string","description":"NCBI scientific name."},"lineage":{"type":["string","null"],"description":"NCBI lineage, ' > '-joined."},"blurb":{"type":["string","null"],"description":"Derived from the lineage walk only — no biological claim beyond NCBI's tree."},"spineLabel":{"type":"string","description":"NCBI release label."},"knownAs":{"type":"array","description":"All names NCBI holds for the taxid.","items":{"type":"object","properties":{"name":{"type":"string"},"class":{"type":"string","enum":["current","synonym","equivalent"]}}}},"cells":{"type":"object","description":"Per-database list of per-release cells, in manifest order.","properties":{"gtdb":{"type":"array","items":{"$ref":"#/components/schemas/DbReleaseCell"}},"silva":{"type":"array","items":{"$ref":"#/components/schemas/DbReleaseCell"}},"gg2":{"type":"array","items":{"$ref":"#/components/schemas/DbReleaseCell"}},"ehomd":{"type":"array","items":{"$ref":"#/components/schemas/DbReleaseCell"}}}},"defaults":{"type":"object","description":"The default release per database.","properties":{"gtdb":{"type":"string"},"silva":{"type":"string"},"gg2":{"type":"string"},"ehomd":{"type":"string"}}},"drift":{"type":"array","description":"Databases that renamed or dropped this taxon across the releases we hold, whether or not the request pinned them. The same hint as /translate rows[].drift, one per database with 'absent' taking precedence over 'renamed'; an 'absent' entry carries alsoRenamed when the name also moved. Omitted when every database is stable.","items":{"$ref":"#/components/schemas/Drift"}},"ranks":{"type":"array","description":"The NCBI lineage one level at a time with nodes.dmp's rank, ending with the species. Omitted when no lineage is held.","items":{"$ref":"#/components/schemas/Rank"}}}},"Rank":{"type":"object","description":"One level of a lineage. rank is the label the source gave that level, or null when it gave none; it is never inferred from position.","required":["rank","name"],"properties":{"rank":{"type":["string","null"]},"name":{"type":"string"}}},"DbReleaseCell":{"type":"object","description":"What one database says about the taxon in one release.","properties":{"db":{"type":"string","enum":["gtdb","silva","gg2","ehomd"]},"release":{"type":"string"},"label":{"type":"string"},"name":{"type":["string","null"],"description":"null when this release has no record for the taxon."},"parts":{"type":"array","items":{"type":"string"},"description":"Split names already parsed from the 'A / B (+n)' display string."},"more":{"type":"integer","description":"How many names beyond `parts` exist, from the '(+N)' marker."},"status":{"type":"string","enum":["current","split"]},"splitCount":{"type":"integer"},"genomeCount":{"type":"integer","description":"Supporting genomes (GTDB/GG2) or taxmap rows (SILVA)."},"lineage":{"type":"string"},"ranks":{"type":"array","description":"The lineage one level at a time with the source's own rank label. Present whenever lineage is. GTDB and Greengenes2 labels come from their d__/p__ prefixes, SILVA's from its tax_slv map, eHOMD's from its published columns; a level the source did not label has rank null.","items":{"$ref":"#/components/schemas/Rank"}},"id":{"type":"string","description":"Database-native record id (e.g. a SILVA accession)."},"aliases":{"type":"array","items":{"type":"string"},"description":"Best-supported names, capped — compare with nameCount."},"nameCount":{"type":"integer","description":"True number of distinct names, even when aliases is capped."},"via":{"$ref":"#/components/schemas/JoinVia"},"absent":{"$ref":"#/components/schemas/Absence"},"sourceUrl":{"type":"string"}}},"JoinVia":{"type":"object","description":"How a release was linked to the NCBI taxon. Present whenever the release holds a record and the join route is one this API version knows; a route it does not recognise omits the field rather than guessing. So where a cell has a name, treat a missing via as unknown, never as exact. (A cell with name: null has no join at all, and never carries via.) A cell aggregates many source rows, so this reports the WEAKEST route any of them took — on a taxon with thousands of genomes an inexact kind may describe a small minority of them. taxid = the source's own NCBI taxid named this species (exact); species-col = GTDB's own ncbi_species_taxid column; merged = followed NCBI's merged.dmp forward from a retired taxid; rank-walk = walked UP NCBI's tree from a strain/subspecies to its species ancestor (never above species); name = joined by binomial against NCBI's name index (SILVA, whose taxmap we ingest carries no NCBI ids); accession = joined transitively through a GTDB genome accession (Greengenes2).","required":["kind"],"properties":{"kind":{"type":"string","enum":["taxid","species-col","merged","rank-walk","name","accession"]},"steps":{"type":"integer","description":"rank-walk only: levels climbed in NCBI's tree from the strain/subspecies record to the species. Parent hops, not rank boundaries — NCBI has unranked nodes below species."},"backbone":{"type":"string","description":"accession only: the GTDB release whose accessions mediated the join."}}},"Absence":{"type":"string","enum":["not-covered","out-of-scope-or-not-present","in-other-releases","not-found"],"description":"Why a release holds no record for a taxon. Every value is read off data we hold; none guesses at the source's reasons. not-covered = the release is a clustered subset export (ReleaseInfo.subset), so the taxon may well be in the database. out-of-scope-or-not-present = the database covers a limited scope (ReleaseInfo.scope; eHOMD is the human oral and aerodigestive microbiome), so absence is not evidence of removal and we cannot tell the two apart. in-other-releases = another release of this database we hold names the taxon (see drift for which). not-found = no release of this database we hold names it."},"ApiError":{"type":"object","required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"string"},"matchType":{"type":"string","description":"On a /taxon name miss: how the lookup ended (none, deleted)."},"candidates":{"type":"array","description":"On a /taxon name miss where the binomial names two or more NCBI taxa: the taxa it could mean. Re-ask by taxid.","items":{"$ref":"#/components/schemas/Candidate"}}}},"Versions":{"type":"object","description":"Available database releases + defaults (from GET /api/v1/versions).","properties":{"apiVersion":{"type":"string","const":"1"},"defaults":{"type":"object","properties":{"gtdb":{"type":"string"},"silva":{"type":"string"},"gg2":{"type":"string"},"ehomd":{"type":"string"}}},"spine":{"type":"string","description":"NCBI release label."},"spineSource":{"$ref":"#/components/schemas/Source"},"databases":{"type":"object","description":"Per-db list of ReleaseInfo objects: release, label, released, releasedFrom, source, and where they apply backbone, subset and scope.","properties":{"gtdb":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseInfo"}},"silva":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseInfo"}},"gg2":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseInfo"}},"ehomd":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseInfo"}}}}}},"ReleaseInfo":{"type":"object","description":"One held release of a database. backbone (Greengenes2 only) is the GTDB release whose genome accessions mediated the join. subset marks a release built from a clustered subset export (SILVA 144 ships only its Ref NR 99 taxmap): a taxon missing from such a release has not been dropped by the database, so drift never reports it as absent there, and a /diff with it as 'to' counts those taxa in lostFromTo without that meaning a removal. scope names the slice of life the database covers (eHOMD: the human oral and aerodigestive microbiome); absence from a scoped database says nothing about the taxon, and cells report it as out-of-scope-or-not-present.","properties":{"release":{"type":"string"},"label":{"type":"string"},"backbone":{"type":"string"},"subset":{"type":"boolean","const":true},"released":{"type":"string","description":"Year and month the database published this release, YYYY-MM. Omitted when the database publishes no date."},"releasedFrom":{"type":"string","description":"Where the released month came from, or why there is none, in words."},"scope":{"type":"string"},"source":{"$ref":"#/components/schemas/Source"}}},"Source":{"type":"object","description":"What was ingested to build a release (or the NCBI spine): where it came from and the exact input bytes, so a result can be tied to a snapshot. sha256 is of the file as the build read it. Some cannot be checked against the upstream download: GTDB releases before R220 (R207, R214) ship as a .tar.gz that is unpacked and re-gzipped before the build, and the NCBI spine hashes four .dmp files extracted from the taxdump.tar.gz that its url names. The same object also appears on the from and to releases of /api/v1/diff.","properties":{"url":{"type":"string","description":"Upstream download location. The exact file for releases built from one file; for GTDB, which reads two files, the release directory."},"files":{"type":"array","description":"Every raw input file the release's build stream read.","items":{"type":"object","properties":{"path":{"type":"string","description":"Relative to the build's data/raw directory."},"sha256":{"type":"string","description":"Lowercase hex, 64 characters."},"bytes":{"type":"integer"}}}},"note":{"type":"string","description":"Present when the url alone does not identify the snapshot (the NCBI spine: the url is overwritten daily). Use the sha256s."},"recordCount":{"type":"integer","description":"Taxids in the release's pack. For the spine, the number of named NCBI taxa shipped in the spine."}}},"Health":{"type":"object","description":"Readiness plus the data snapshot being served (from GET /api/v1/health).","properties":{"apiVersion":{"type":"string","const":"1"},"ok":{"type":"boolean","const":true},"spine":{"type":"string","description":"NCBI release label, the same string as `spine` on /api/v1/versions."},"spineId":{"type":"string","description":"Spine pack id, e.g. ncbi-2026-10-23."},"defaults":{"type":"object","properties":{"gtdb":{"type":"string"},"silva":{"type":"string"},"gg2":{"type":"string"},"ehomd":{"type":"string"}}},"releases":{"type":"object","description":"Held release strings per database.","properties":{"gtdb":{"type":"array","items":{"type":"string"}},"silva":{"type":"array","items":{"type":"string"}},"gg2":{"type":"array","items":{"type":"string"}},"ehomd":{"type":"array","items":{"type":"string"}}}}}},"ReleaseDiff":{"type":"object","properties":{"apiVersion":{"type":"string","const":"1"},"db":{"type":"string"},"from":{"$ref":"#/components/schemas/ReleaseInfo"},"to":{"$ref":"#/components/schemas/ReleaseInfo"},"summary":{"type":"object","properties":{"shared":{"type":"integer"},"renamed":{"type":"integer"},"unchanged":{"type":"integer"},"gainedInTo":{"type":"integer"},"lostFromTo":{"type":"integer"}}},"renamed":{"type":"array","items":{"type":"object","properties":{"taxid":{"type":"string"},"ncbi":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"}}}},"renamedTruncated":{"type":"integer","description":"renamed entries omitted past the 500 cap"}}}}}}