Pipeline Registry API

seqdesk.org publishes a small set of read-only, unauthenticated JSON endpoints. They are the supply side of a SeqDesk installation: your instance calls them to list installable pipelines, download a package payload, refresh its MIxS checklist catalog, and find out whether a newer release exists.

None of these endpoints see your data, and none of them require a key. They are CDN-cached and CORS-open, so a browser, a script, or an air-gapped mirror can all consume them the same way.

For endpoints on your own instance — orders, samples, runs, uploads — see the App API instead. For the sequencing hardware catalog, which follows a different contract, see the Sequencing Technology API.

Base URL

• Public registry: https://seqdesk.org/api
• A private or air-gapped mirror: whatever host serves the same paths

A SeqDesk instance points at the public registry by default. Changing that is a configuration decision, not an API one.

Endpoints

1. List available pipelines

curl -s https://seqdesk.org/api/registry

The index is one JSON document with a pipelines array and a categories array:

{
  "version": "1.0.0",
  "lastUpdated": "2026-05-22",
  "baseUrl": "https://seqdesk.org/api/registry",
  "pipelines": [
    {
      "id": "fastqc",
      "name": "FastQC",
      "shortName": "fastqc",
      "shortDescription": "Run FastQC quality control on linked FASTQ files in an order.",
      "category": "order-utilities",
      "tags": ["order", "qc", "fastqc", "fastq"],
      "author": "SeqDesk",
      "provider": "SeqDesk",
      "latestVersion": "0.1.0",
      "versions": [
        { "version": "0.1.0",
          "downloadUrl": "https://seqdesk.org/api/registry/pipelines/fastqc/0.1.0/download" }
      ],
      "verified": true,
      "featured": false,
      "status": "available",
      "icon": "CheckCircle",
      "targets": { "supported": ["order"] },
      "capabilities": {
        "requiresLinkedReads": true,
        "writesCanonicalReadMetadata": true,
        "writesCanonicalReadFiles": false
      }
    }
  ],
  "categories": [
    { "id": "metagenomics", "name": "Metagenomics", "description": "Microbial community analysis" },
    { "id": "submission", "name": "Submission", "description": "Data submission and archival workflows" },
    { "id": "quality-control", "name": "Quality Control", "description": "Read quality summaries and linked FASTQ checks" },
    { "id": "order-utilities", "name": "Order Utilities", "description": "Order-scoped utilities for simulation, validation, and read QC" }
  ]
}

Each pipeline’s category matches one of the four categories[].id values, and clients group the catalog by them.

Two top-level fields are easy to misread. version is the schema version of the index document itself, currently 1.0.0 — it has nothing to do with any pipeline’s version. lastUpdated is the date the catalog was last edited.

2. Fetch one pipeline definition

curl -s https://seqdesk.org/api/registry/mag

Returns the full entry for that pipeline: description, DAG steps, tools, requirements, and every block described below. This is what the in-app pipeline store renders on a package’s detail page.

The id must match ^[a-z0-9-]+$ — anything else is rejected before the file system is touched.

3. Download a package version

curl -s https://seqdesk.org/api/registry/pipelines/mag/3.0.0/download

Returns the packaged payload SeqDesk installs: the manifest.json, definition.json, registry.json, samplesheet generator, and any parser or discovery scripts the package needs. See the package contract for what those files mean.

version must match ^[a-z0-9]+(\.[a-z0-9]+)*$.

Entry metadata blocks

Beyond the display fields, a catalog entry may carry four optional blocks. They exist so a client can filter and gate the catalog without downloading anything.

targets — where the package can run

{ "id": "simulate-reads", "targets": { "supported": ["order"] } }

• study — the package operates across a study’s samples
• order — the package operates on one sequencing order’s samples

A package is offered only in contexts it declares. Attempting to create a run for an unsupported target is refused by the instance with Pipeline <id> does not support <target> targets.

capabilities — what the package does to your data

{
  "requiresLinkedReads": true,
  "writesCanonicalReadMetadata": false,
  "writesCanonicalReadFiles": false,
  "stagesReadCandidates": true,
  "requiresAdminReadPromotion": true
}

Only requiresLinkedReads, writesCanonicalReadMetadata, and writesCanonicalReadFiles appear on every entry; the two candidate flags are present only where they apply. Treat a missing flag as false.

The last two are the important pair: they are how a read-cleaning package announces that its output will land in the pending-writeback review flow rather than silently replacing an order’s reads.

sequencingCompatibility — which data the package suits

{
  "readLengthClass": "short",
  "readLayouts": ["paired"],
  "platformFamilies": ["illumina", "mgi", "bgi", "ion-torrent"]
}

Used to warn — or refuse — when a package is pointed at data it was not built for, for example a short-read assembler given nanopore reads. platformFamilies values line up with the platformFamily field in the Sequencing Technology API.

source — how the package is installed

{
  "id": "metaxpath",
  "isPrivate": true,
  "licenseRequired": true,
  "status": "private",
  "source": {
    "kind": "github",
    "label": "GitHub",
    "repository": "hzi-bifo/MetaxPath-Nextflow",
    "refDefault": "main",
    "descriptorPath": ".seqdesk/pipelines/metaxpath",
    "includeWorkflow": true,
    "keyLabel": "GitHub token"
  }
}

Entries with isPrivate: true appear in the catalog so an operator can see they exist and what they would need, but their payload is not served publicly. keyLabel is what the install dialog calls the credential it asks for.

databases — reference data the package needs

{
  "databases": [
    {
      "id": "gtdb",
      "label": "GTDB-Tk Database",
      "version": "214.1",
      "fileName": "gtdbtk_r214_data.tar.gz",
      "downloadUrl": "https://data.ace.uq.edu.au/public/gtdb/…/gtdbtk_r214_data.tar.gz",
      "configKey": "gtdbDb",
      "mode": "ensure"
    }
  ]
}

Reference databases are large, downloaded separately, and stored outside the release directory. configKey names the pipeline config key the extracted path is written to, so the download step and the run step agree on where the data lives.

4. MIxS checklists

GET /registry/mixs

The curated ENA MIxS environment packages, with a monotonic top-level version. SeqDesk instances call this cross-origin to discover and refresh their checklist catalog; the same version is what a study pins in Study.mixsVersion so an older study keeps rendering the fields it was authored with.

curl -s https://seqdesk.org/api/registry/mixs
curl -s "https://seqdesk.org/api/registry/mixs?accession=ERC000022"

Without a query parameter you get { version, checklists: [ … ] } — every checklist, each with an optional image merged in from a separately maintained illustration map. With ?accession= you get { version, checklist: { … } } for that one checklist, or 404 {"error":"Unknown MIxS checklist accession: ERC000022"}.

Illustrations are stored apart from the checklist data on purpose, so regenerating the checklists from ENA can never silently drop them.

5. Release feed

{
  "latest": {
    "version": "1.2.0",
    "channel": "stable",
    "releaseDate": "2026-05-22",
    "downloadUrl": "https://…/seqdesk-1.2.0.tar.gz",
    "checksum": "…",
    "releaseNotes": "…",
    "minNodeVersion": "22.13.0",
    "databaseRequirement": "postgresql"
  },
  "updateAvailable": false,
  "currentVersion": "1.2.0"
}

updateAvailable is a numeric semantic-version comparison, not a string comparison, so 1.1.10 correctly counts as newer than 1.1.9. Without ?current= it is always false. If no release exists for the requested channel the endpoint returns 404 {"error":"No releases found for channel"}.

This endpoint is what the in-app updater polls; see Automatic Updates for the client side. Unlike the pipeline endpoints it is served uncached (Cache-Control: no-store), because a release must be visible the moment it is published.

Errors, caching, and CORS

/registry/{id} and the download endpoint validate their path parameters before touching anything:

Caching and cross-origin behaviour:

• Pipeline and MIxS endpoints are served with Cache-Control: public, s-maxage=300, stale-while-revalidate=600. A newly published package can therefore take up to five minutes to appear at the edge.
• /registry, /registry/{id}, /registry/pipelines/{id}/{version}/download, and /registry/mixs send Access-Control-Allow-Origin: * and answer OPTIONS with 204, so they are callable from a browser.
• /version is explicitly uncached.

Research-data tracker

A read-only snapshot of the research-data tracker — public-archive metrics such as sequence reads, dataset DOIs, structures, and FAIR-paper citations, re-queried weekly. It is unrelated to pipelines but shares the same public, unauthenticated style, which makes it convenient for pulling current numbers into a slide deck or notebook.

Filters combine, so ?category=sequence-archives&latest=1 gives the current value of every sequence-archive metric.

{
  "schemaVersion": 1,
  "generatedAt": "2026-07-27T04:12:00.000Z",
  "asOf": "2026-07-27",
  "license": "Compiled aggregate counts (facts) re-served by SeqDesk under each source's terms…",
  "categories": { "sequence-archives": "Sequence archives", "fair-literature": "FAIR adoption & literature" },
  "count": 1,
  "metrics": [
    {
      "id": "ena-read-run",
      "label": "ENA raw read datasets",
      "category": "sequence-archives",
      "source": "EMBL-EBI / European Nucleotide Archive",
      "unit": "runs",
      "flagship": true,
      "cadence": "weekly",
      "series": [["2026-06-24", 42613406], ["2026-07-01", 42981220]]
    }
  ]
}

categories is a full id-to-label map, count is the number of metrics after filtering, and each series is chronological. The response is cached for an hour (s-maxage=3600, stale-while-revalidate=86400). The license string is part of the payload for a reason — these are aggregate counts re-served under each upstream source’s terms, and it names them.

Related reading

• Adding Pipelines — installing a package from this registry into an instance
• Available Pipelines — what each catalog entry actually does
• Architecture — the files inside a downloaded payload
• Automatic Updates — the client side of /version