Skip to content

REST API Overview

Official docs exist for most of this — read them first

The core upload/validation/status/report/workspace endpoints are already officially documented under Data Upload API (Endpoints, Authentication, Examples), with the real base URL, curl examples, and response payloads. This page is a quick-reference summary of those endpoints plus coverage of the newer S3 presigned/multipart upload endpoints, which aren't in the official docs yet (found by reviewing the immport-data-upload-api source directly).

Authentication

Create a scoped API key at https://www.dev.immport.org/auth/api/keys and send it as Authorization: Bearer <api_key> on every request. See Authentication for the full walkthrough.

Already documented (see official pages for full detail)

Method & Path Purpose
GET /workspaces List workspaces you can upload to
GET /data/upload/documentation/templates/{workspaceId} Download pre-populated templates for a workspace
POST /data/upload/type/online Upload file(s)/zip and perform the upload in one call
POST /data/upload/type/offline Reserve an upload ticket for a large package delivered out-of-band (e.g. Aspera)
POST /data/upload/validation Validate an upload identified by uploadTicketNumber
GET /data/upload/registration/{uploadTicketNumber}/status Poll status
GET /data/upload/registration/{uploadTicketNumber}/reports/summary Per-row/error summary (completed or rejected jobs)
GET /data/upload/registration/{uploadTicketNumber}/reports/database What was loaded (completed jobs only)

Not yet in the official docs: direct-to-S3 uploads

For files too large for a simple multipart POST (e.g. .fcs, sequencing reads), the service also exposes an S3 presigned-URL flow:

Single file:

  1. GET /data/upload/s3/presigned-upload-url — params: workspaceId, fileName, packageName (optional), uploadPurpose, uploadNotes (optional), objectKey (optional). Returns a pre-signed S3 PUT URL.
  2. Upload the file bytes directly to that URL (not through this API).
  3. POST /data/upload/s3/presigned-upload-url/complete — body: fileName, objectKey, uploadTicketNumber, uploadPurpose, packageSize.

Multipart (chunked):

  1. POST /data/upload/s3/multipart/initiate (one file) or /initiate-multiple (several), specifying totalParts per file.
  2. Upload each part to the returned pre-signed part URLs.
  3. GET /data/upload/s3/multipart/status — poll uploaded parts (supports resuming).
  4. POST /data/upload/s3/multipart/complete — finalize with each part's partNumber/eTag.
  5. POST /data/upload/s3/multipart/abort — cancel.

Verify before relying on this

This section was reverse-engineered from the S3PresignedUploadController source in immport-data-upload-api, not from a published spec — confirm parameter names against the live server (or ask the ImmPort Helpdesk) before building production automation on it.

A note on the existing MCP Server

ImmPort already runs an MCP Server (Beta) at https://mcp.immport.org — but it's a read/query surface (search_studies, get_assay_results, get_study_data, etc.) for already-published data, not a submission interface. There is currently no equivalent MCP server for the upload side of ImmPort. This knowledge base section (API reference + workflows + validation glossary) is intended as the groundwork for building one.

See also

End-to-End Upload Recipe for the end-to-end sequence these endpoints are meant to be called in.