Skip to content

Automate with the API

The Data Upload API covers everything the upload website does: fetch templates, upload a package, validate it, poll the status and download reports. Full endpoint details, base URLs and curl examples are in the official Data Upload API documentation. This page shows how the calls fit together.

The upload loop

sequenceDiagram
    autonumber
    participant C as Your script
    participant API as Data Upload API
    participant S3 as S3 (large files)
    C->>API: GET /workspaces
    C->>API: GET /data/upload/documentation/templates/{workspaceId}
    Note over C: Fill in templates and zip the package
    alt Package up to 512 MB
        C->>API: POST /data/upload/type/online (zip attached)
    else Large raw files
        C->>API: Request presigned or multipart upload URLs
        C->>S3: PUT file bytes
        C->>API: Complete the S3 upload
    end
    API-->>C: uploadTicketNumber
    C->>API: POST /data/upload/validation
    loop until not Pending
        C->>API: GET /data/upload/registration/{ticket}/status
    end
    alt Rejected
        C->>API: GET .../{ticket}/reports/summary
        Note over C: Fix the errors and upload again
    else Completed
        C->>API: GET .../{ticket}/reports/database
    end

Step by step

  1. Authenticate. Create a scoped API key at https://www.dev.immport.org/auth/api/keys and send it on every request as Authorization: Bearer <api_key> (Authentication). The key's account must be a Submitter or Administrator on the workspace (roles).
  2. Find your workspace. GET /workspaces lists the workspaces you can upload to. There is no API for creating workspaces; use the request form.
  3. Get templates. GET /data/upload/documentation/templates/{workspaceId} returns a zip of templates for the workspace. Use the Template Finder or the machine-readable data to decide which ones you need and how to group them.
  4. Upload.
    • POST /data/upload/type/online: attach the zip and upload in one call.
    • POST /data/upload/type/offline: reserve a ticket now and deliver a large package separately, for example with Aspera.
    • For large raw files, use the S3 upload endpoints.
  5. Validate. POST /data/upload/validation with the uploadTicketNumber from the upload.
  6. Poll. GET /data/upload/registration/{uploadTicketNumber}/status until the status is no longer Pending.
  7. Read the reports. On Rejected, GET .../reports/summary lists the errors. Look them up in Troubleshooting Errors, fix them and go back to step 4. On Completed, GET .../reports/database shows what was loaded and the accessions assigned.

Retries

If a status call fails, it's safe to poll again. Don't re-send POST /data/upload/validation for a package that may already have loaded rows; it can produce duplicate user-defined ID errors (E-04). Check the status first.

One study per package

Each upload ticket can contain data for only one study (R-01). Send each study as its own package.

Large files: direct to S3

For files too big for a single request, such as .fcs files or sequencing reads, the service can hand out pre-signed S3 URLs.

Not yet in the official API reference

These endpoints aren't in the official API documentation yet. Confirm the parameter names with the ImmPort Helpdesk before you build production automation on them.

Single file

  1. GET /data/upload/s3/presigned-upload-url with workspaceId, fileName, uploadPurpose, and optionally packageName, uploadNotes, objectKey. Returns a pre-signed PUT URL.
  2. PUT the file bytes to that URL, directly to S3.
  3. POST /data/upload/s3/presigned-upload-url/complete with fileName, objectKey, uploadTicketNumber, uploadPurpose, packageSize.

Multipart (chunked, resumable)

  1. POST /data/upload/s3/multipart/initiate for one file, or /initiate-multiple for several, giving totalParts for each file.
  2. PUT each part to its pre-signed URL.
  3. GET /data/upload/s3/multipart/status lists the parts already uploaded, so an interrupted upload can resume.
  4. POST /data/upload/s3/multipart/complete with each part's partNumber and eTag.
  5. POST /data/upload/s3/multipart/abort cancels the upload.

Endpoint summary

Method and path Purpose
GET /workspaces List workspaces you can upload to
GET /data/upload/documentation/templates/{workspaceId} Download templates for a workspace
POST /data/upload/type/online Upload a zip and start processing
POST /data/upload/type/offline Reserve a ticket for a package delivered separately
POST /data/upload/validation Validate an upload by uploadTicketNumber
GET /data/upload/registration/{uploadTicketNumber}/status Upload status
GET /data/upload/registration/{uploadTicketNumber}/reports/summary Errors and row counts (completed or rejected)
GET /data/upload/registration/{uploadTicketNumber}/reports/database What was loaded (completed only)

The ImmPort MCP server is for querying released data, not for submitting it. To help an AI assistant prepare a submission, see Using these docs with AI agents.