App API

This page documents HTTP endpoints exposed by an installed SeqDesk instance — the in-app API surface, as opposed to the public seqdesk.com endpoints covered by the Pipeline API. Most are used by the SeqDesk UI itself, but they are stable enough to call from automation, scripts, or external tools.

All endpoints live under /api/ on your SeqDesk host. Authentication uses the standard NextAuth session cookie unless noted.

Form schemas

The dynamic form configuration is exposed read-only so external tooling can mirror the same field set the SeqDesk UI renders.

`GET /api/form-schema`

Returns the order-form schema as configured by the facility admin in the Order Form Builder.


{
  "fields": [ { "id": "...", "name": "library_strategy", "type": "select", "options": [...], "required": true, "groupId": "..." } ],
  "groups": [ { "id": "group_sequencing", "name": "Sequencing Information", "icon": "Dna", "order": 1 } ],
  "version": "2026-04-01T00:00:00Z",
  "enabledMixsChecklists": ["ERC000022"],
  "perSampleFields": ["sample_name", "barcode"]
}

The response is filtered by the caller’s role: facility-admin-only fields are omitted for researchers.

`GET /api/study-form-schema`

Same shape, but for the study metadata form. Includes additional studyFields and modules keys describing study-level vs. sample-level fields and which modules’ fields are currently enabled.

MIxS checklists

MIxS is the GSC’s Minimum Information about a Sequence checklist standard. SeqDesk ships checklist definitions and field templates; admins enable specific checklists through the form builder, and researchers see the corresponding required fields when filling out study metadata.

`GET /api/mixs-checklists`

List all available checklists.


curl https://your-host/api/mixs-checklists


{
  "checklists": [
    {
      "name": "soil",
      "file": "soil-checklist.json",
      "fieldCount": 53,
      "mandatoryCount": 12,
      "accession": "ERC000022"
    }
  ],
  "total": 16
}

Single-checklist lookup with ?accession= or ?name=:


curl https://your-host/api/mixs-checklists?accession=ERC000022

Returns the full checklist definition including every field, its data type, unit options, MIxS section, and whether it is mandatory.

`GET /api/mixs-templates`

The same field definitions but in template form, ready to be embedded in the form builder. ?name=<checklist> returns templates for one checklist.

Pipeline weblog

Nextflow runs are configured to POST execution events to the SeqDesk weblog endpoint. The endpoint also accepts events from other pipeline-runtime adapters (SLURM trace, queue updates, internal step events). See Pipeline Runtime for the client-side configuration.

`POST /api/pipelines/weblog`

Each call records one PipelineRunEvent.


{
  "runId": "ckxx...",
  "eventType": "process_completed",
  "processName": "MAG:ASSEMBLY:MEGAHIT",
  "stepId": "step_3",
  "status": "COMPLETED",
  "message": "exit 0",
  "payload": { "trace": { "duration": "00:43:12", "%cpu": "812", "rss": "12.3 GB" } },
  "source": "weblog"
}

Event types and sources

The source field categorizes where an event came from. Recognized values:

Source	Meaning
`weblog`	Nextflow `-with-weblog` payload
`trace`	Parsed `.nextflow/trace.txt` row
`queue`	SLURM queue poller (e.g., a step transitioned `PD → R`)
`process`	Internal SeqDesk step lifecycle event

Common eventType values include run_started, run_completed, process_submitted, process_started, process_completed, process_failed. Anything ingested without a recognized type is still stored verbatim — the server does not gate-keep on the value, so custom adapters can add their own.

Multipart upload flow

The order page uses a chunked upload protocol when researchers attach reads, checksums, or other artifacts to a sample. Build automation that mimics the same flow when bulk-loading data.

`POST /api/orders/[orderId]/sequencing/uploads`

Initiate an upload session.


{
  "targetKind": "READS",
  "targetRole": "SAMPLE_READ_FORWARD",
  "originalName": "S1_R1.fastq.gz",
  "expectedSize": 1843921023,
  "checksumProvided": "md5:6f1b...",
  "mimeType": "application/gzip",
  "metadata": { "sampleId": "smpl_..." }
}

Response:


{
  "success": true,
  "uploadId": "upl_...",
  "tempPath": "/var/seqdesk/uploads/.tmp/upl_.../S1_R1.fastq.gz",
  "expectedSize": 1843921023
}

Stream chunks to tempPath (the upload protocol is server-local; the path is returned because the same install also exposes a chunked-PUT for remote runners). When the file is fully written, call complete.

`POST /api/orders/[orderId]/sequencing/uploads/[uploadId]/complete`


{
  "success": true,
  "finalPath": "/var/seqdesk/data/orders/.../S1_R1.fastq.gz",
  "receivedSize": 1843921023,
  "checksumComputed": "md5:6f1b..."
}

If checksumProvided was supplied at initiate, the complete call verifies the computed checksum against it before promoting the file out of .tmp.

File operations

These endpoints back the in-app file browser and assembly downloader. They respect demo-session restrictions (Demo mode) and the allowUserAssemblyDownload setting.

`GET /api/files/download?path=<rel>`

Streams a file. Path is resolved relative to the configured data base path and validated against directory traversal. Demo sessions get 403.

`GET /api/files/preview?path=<rel>`

Serves an HTML report (e.g., FastQC, MultiQC) inline with strict CSP headers. Useful for embedding QC reports in the SeqDesk UI without downloading.

`POST /api/files/checksum`

Computes MD5 for a list of paths and updates the Read record (if any) for each. Useful as a one-shot integrity audit.


// Request
{ "filePaths": ["orders/abc/S1_R1.fastq.gz", "orders/abc/S1_R2.fastq.gz"] }
 
// Response
{
  "results": [
    { "filePath": "orders/abc/S1_R1.fastq.gz", "checksum": "md5:6f1b...", "updatedReadRecord": true }
  ],
  "summary": { "total": 2, "successful": 2, "failed": 0, "updatedReadRecords": 2, "notLinkedToRead": 0 }
}

`POST /api/files/delete`

Bulk-delete a list of paths. Removes the file from disk and clears any referencing Read records. Idempotent on already-deleted entries.

Sequencing run import

`POST /api/orders/[orderId]/sequencing/runs/import`

Accepts a multipart form with a CSV or Excel attachment describing run plans — one row per (runId, sampleCode, barcode) triple. Used by the “Import run plan” button on the sequencing tab of the order detail page.


{
  "runs": [
    { "runId": "RUN-2026-04-30-001", "samples": [
      { "sampleCode": "S1", "barcode": "BC01" },
      { "sampleCode": "S2", "barcode": "BC02" }
    ] }
  ],
  "errors": [
    { "rowNumber": 7, "message": "Unknown sample code 'S99'" }
  ]
}

The endpoint upserts SequencingRun and SequencingRunSample rows. Rows that fail validation come back in errors without aborting the rest.

Conventions

All POST endpoints accept application/json unless they explicitly take a multipart body (the run import is the main exception).
Errors return { "error": "<message>" } with an appropriate 4xx/5xx status.
Endpoints mutating state require FACILITY_ADMIN unless the caller owns the entity (e.g., a researcher can upload to their own order).
Pagination uses ?cursor=<id>&limit=<n> where supported.