Pipeline API

SeqDesk exposes read-only API endpoints for discovering available study pipelines and order-scoped sequencing utilities, fetching their metadata, and downloading versioned packages. The registry is also the default manifest source used by SeqDesk pipeline installs.

For sequencing-technology endpoints see the Sequencing Technology API.

Base URL

Use your deployment host with /api:

• Public SeqDesk: https://seqdesk.com/api
• Self-hosted: https://<your-host>/api

Endpoints

Usage Examples

1. List available pipelines

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

Response shape:

{
  "version": "1.0.0",
  "lastUpdated": "2026-03-06",
  "baseUrl": "https://seqdesk.com/api/registry",
  "pipelines": [
    {
      "id": "fastqc",
      "latestVersion": "0.1.0",
      "targets": {
        "supported": ["order"]
      },
      "capabilities": {
        "requiresLinkedReads": true,
        "writesCanonicalReadMetadata": true,
        "writesCanonicalReadFiles": false,
        "stagesReadCandidates": false,
        "requiresAdminReadPromotion": false
      },
      "versions": [
        {
          "version": "0.1.0",
          "downloadUrl": "https://seqdesk.com/api/registry/pipelines/fastqc/0.1.0/download"
        }
      ]
    }
  ],
  "categories": [
    { "id": "metagenomics", "name": "Metagenomics", "description": "Microbial community analysis" },
    { "id": "quality-control", "name": "Quality Control", "description": "Read quality summaries and linked FASTQ checks" }
  ]
}

Alongside pipelines, the index includes a categories array ({ id, name, description }) that clients use to group the catalog; each pipeline’s category matches one of these ids.

2. Fetch one pipeline definition

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

This returns the full pipeline metadata (description, DAG steps, requirements, features, etc.).

3. Download a specific package version

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

This returns the packaged payload (for example manifest.json, definition.json, parser configs, and templates) used by SeqDesk to install or run that pipeline version.

Target Metadata

Registry entries may include a targets block describing where a package is intended to run:

• study: pipelines that operate at study scope
• order: pipelines that operate at order scope

Example:

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

Capability Metadata

Registry entries may also include capabilities to support lightweight catalog filtering and UI hints in SeqDesk clients.

Current capability flags:

• requiresLinkedReads
• writesCanonicalReadMetadata
• writesCanonicalReadFiles
• stagesReadCandidates
• requiresAdminReadPromotion

Source Metadata

Registry entries may include a source block describing how SeqDesk should install that pipeline:

• registry: public package payload
• privateRegistry: private endpoint requiring a key/token
• github: GitHub repo/ref descriptor import

Example:

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

Error Responses

/registry/{id} and /registry/pipelines/{id}/{version}/download validate path parameters and return:

• 400 for invalid IDs/versions
• 404 for unknown pipeline/package
• 500 for server-side load errors

Caching and CORS

• Pipeline endpoints are served with CDN cache headers (s-maxage=300, stale-while-revalidate=600).
• Browser-accessible cross-origin endpoints include permissive CORS headers (Access-Control-Allow-Origin: *): /registry, /registry/{id}, /registry/pipelines/{id}/{version}/download.

Version API

The response wraps the release in a latest envelope:

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

If no release exists for the requested channel, the endpoint returns 404. This endpoint is consumed by the in-app updater. See Automatic Updates for the client-side flow.