Sequencing Technology API

SeqDesk keeps a curated catalog of sequencing hardware: platforms, devices, flow cells, kits, barcode schemes, and control software. The catalog drives the technology selector on the order form, feeds compatibility hints to pipelines, and supplies the images shown next to each device.

There are two distinct use cases, and they use different endpoints:

The second is the interesting one. A facility that runs instruments the public catalog does not cover can host its own JSON document and point SeqDesk at it — this page is the contract that document must satisfy.

Base URL

• Public registry: https://seqdesk.org/api
• Your instance: https://<your-host>/api

The registry a SeqDesk instance syncs from defaults to https://seqdesk.org/api/registry/sequencing-tech, overridable per instance by the syncUrl stored with the configuration, or globally by the SEQDESK_API_URL environment variable.

Reading your instance’s catalog

GET /api/sequencing-tech

Returns the locally stored configuration after filtering. Unauthenticated — the order form needs it before a session is fully established — and served Cache-Control: no-store, because it must reflect an admin’s edits immediately.

curl -s https://<your-host>/api/sequencing-tech

{
  "technologies": [
    {
      "id": "ont-minion",
      "name": "MinION",
      "manufacturer": "Oxford Nanopore",
      "shortDescription": "Portable nanopore sequencing platform",
      "platformFamily": "oxford-nanopore",
      "readLengthClass": "long",
      "supportedReadLayouts": ["single"],
      "specs": [{ "label": "Read length", "value": "up to 4 Mb" }],
      "pros": [{ "text": "Portable" }],
      "cons": [{ "text": "Lower per-run throughput than PromethION" }],
      "bestFor": ["Rapid turnaround"],
      "available": true,
      "order": 10
    }
  ],
  "devices": [
    {
      "id": "ont-minion-mk1d",
      "platformId": "ont-minion",
      "name": "MinION Mk1D",
      "manufacturer": "Oxford Nanopore",
      "productOverview": "Portable nanopore sequencer",
      "shortDescription": "Portable nanopore sequencing device",
      "specs": [],
      "compatibleFlowCells": ["flo-min114"],
      "compatibleKits": ["sqk-lsk114"],
      "compatibleSoftware": ["minknow"],
      "available": true,
      "order": 10
    }
  ],
  "flowCells": [],
  "kits": [],
  "software": [],
  "barcodeSchemes": [],
  "barcodeSets": []
}

What the filter actually does

The filtering rules are not uniform across collections, which surprises people:

So comingSoon hides a platform or a device from users while leaving it visible in the admin catalog, but it does not hide a flow cell or kit. Use available: false for those.

The response deliberately carries no version and no syncUrl. Those live on the stored configuration and are visible to admins under Admin → Sequencing Technology, not on the public read.

If the catalog cannot be loaded at all, the endpoint returns 500 {"error":"Failed to fetch technologies"}.

Serving a catalog: the sync contract

GET /api/registry/sequencing-tech

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

This returns the full, unfiltered dataset and is exactly the contract SeqDesk accepts when you configure a custom sync URL in Admin → Sequencing Technology.

SeqDesk accepts either a wrapped document:

{ "config": { "version": 6, "technologies": [] } }

or the raw configuration object:

{
  "version": 6,
  "technologies": [],
  "devices": [],
  "flowCells": [],
  "kits": [],
  "software": [],
  "barcodeSchemes": [],
  "barcodeSets": []
}

Anything that is not an object — an array, a string, null — is rejected with “Registry returned invalid sequencing tech config”. Any collection that is not an array is coerced to [] rather than failing, so a partial document is tolerated.

Required fields

Optional collections

A platform entry

A device entry

Kits may additionally carry barcoding metadata — kitKind, doradoKitName, and a barcoding block with barcodeSetId, maxBarcodesPerRun, and compatibleBarcodeKits. SeqDesk treats the appearance of this metadata on an existing kit as an update, even without a version bump, so barcoding data can be backfilled into a catalog that has already been synced.

Asset resolution

icon and image may be relative paths such as /images/sequencers/devices/ont-minion-mk1d.png. SeqDesk resolves them against the origin of the sync URL, so a custom registry can serve its own images from its own host without rewriting the paths. Absolute URLs are passed through unchanged.

Update detection and merging

When an admin checks a registry for updates, SeqDesk fetches the document and decides whether anything changed. It updates if any of these hold:

• the remote version is greater than the local version;
• the local catalog has no technologies and the remote one does;
• the remote contains an id that is missing locally, in any of technologies, devices, flowCells, kits, or software;
• the remote adds barcoding metadata (kitKind, doradoKitName, barcoding, or richer barcoding fields) to a kit that already exists locally, or new barcode schemes or sets.

The last two matter: a registry that adds an entry without bumping version is still picked up. Nothing is deleted — an item that exists locally but not remotely is kept.

Merging is per item, by id:

That exception is the important one. Turning a platform off in your instance survives every future sync, without you having to mark the entry as locally overridden. Set localOverrides: true only when you have edited more than availability — a renamed device, corrected specs, your own image.

After a successful merge SeqDesk stores the remote version, the resolved syncUrl, and lastSyncedAt, and reports how many new technologies arrived.

Custom registry checklist

Errors

Caching and CORS

• The public seqdesk.org registry endpoints are CDN-cached with s-maxage=300, stale-while-revalidate=600. A change you publish can take up to five minutes to reach an instance.
• Your instance’s GET /api/sequencing-tech is served no-store.
• Custom registry sync is a server-side fetch, so CORS headers on your registry are irrelevant to SeqDesk — but adding them lets you test the URL from a browser.

Related reading

• Administration → Sequencing Technologies — the admin screen that consumes this contract
• Pipeline Registry API — how platformFamily gates pipelines
• Data Model — where the synced catalog is stored