Skip to content

Getting Started: Workspaces and Studies

Before any data can be uploaded, you need account access, a workspace, and a registered study. This page summarizes the setup flow from Data Submission Process Guide with the agent/automation angle added.

1. Account

Register at https://www.dev.immport.org/auth/login if you don't already have an ImmPort account. All upload APIs require an authenticated (JWT) identity — see API Reference for how that identity is passed to each endpoint.

2. Workspace

What a workspace is

A workspace is a private, access-controlled container for uploads. Data in it stays private until it's published as a public ImmPort study — and all studies/subjects sharing data should live in the same workspace (see Subject Sharing Across Studies).

Situation Action
New member, no workspace yet Submit the Workspace Request Form
New member, team already has a workspace Have an existing team member submit the request to add you
Existing member, adding another study Reuse your existing workspace — especially if the new study shares subjects with a prior one

For a programmatic/agent client: once credentials are available, call GET /workspaces to enumerate the workspaces you can upload to (see API Reference). There is currently no public self-service "create workspace" API — workspace provisioning goes through the Workspace Request Form / ImmPort Helpdesk, not an automatable endpoint.

3. Register a study

"Registering" a study means populating the metadata that describes its basic design (arms/cohorts, protocols, etc.). There are two independent paths — covered in detail in Two Upload Paths:

  1. Study Registration Wizard (SRW) — a guided online form.
  2. Basic Study Design template — basic_study_design.txt + protocols.txt, uploaded like any other template package.

Which one should an agent use?

If you're scripting submissions and want a single consistent code path (fill template → validate → upload → poll status) for everything — study registration included — prefer the Basic Study Design template path. The SRW is a human-oriented multi-page form; there's no indication it has its own REST API distinct from the template upload pipeline. If you only need to register bare study metadata with no subject/sample data at all, a Study File attached via the SRW may be faster for a human, but less natural for an agent to drive.

Next: Two Upload Paths → Template Catalog → Upload Order.