Skip to content

Overview

ImmPort provides several focused APIs for accessing, uploading, and integrating immunology research data. Below is an overview of the primary API families and their typical use cases.

API Overview

Shared Data API

  • Purpose: Programmatic access to published study metadata, study-level files, assay results, controlled vocabularies, and other read-only shared resources.
  • Notes: Shared Data endpoints are documented with OpenAPI 3.0 and exposed via a Swagger UI for interactive exploration and live requests.

Interactive API Explorer

Use the ImmPort Swagger UI to browse Shared Data API endpoints and make live requests directly from your browser.

Machine-readable OpenAPI 3.0 spec (JSON): https://www.dev.immport.org/data/query/v3/api-docs

GA4GH DRS API

  • Purpose: GA4GH Data Repository Service (DRS) implementation that maps logical DRS object IDs (UUIDs) to physical methods for retrieving shared files.
  • Notes: Recommended for cloud-native retrieval workflows where a DRS object is resolved to a presigned S3 URL or streaming transfer endpoint.
  • Documentation: GA4GH DRS API Overview

HAPI FHIR Server

  • Purpose: A FHIR interface exposing a subset of mapped ImmPort data as FHIR ResearchStudy and related resources for interoperability with clinical research tools.
  • Notes: FHIR endpoints support search and read access to the FHIR-mapped subset. For full dataset access, use the Shared Data API or download options.
  • Documentation: HAPI FHIR API Overview

GeneList Resource

  • Purpose: Curated gene lists published by ImmPort (e.g., immune-related gene sets), distributed as JSON, TXT, and GMT files on the public S3 release bucket.
  • Notes: GeneList documentation includes direct S3 file URLs for programmatic download.
  • Documentation: GeneList Overview

Data Upload / Submission APIs

  • Purpose: Programmatic submission and management of private or workspace-bound data (uploads, manifest submission, and workspace management).
  • Notes: Upload endpoints require an authenticated user with appropriate workspace and study permissions. Use a scoped API key with the upload scope for write operations.
  • Documentation: Data Upload API Overview

ImmPort Auth Service

  • Purpose: Authentication and API key management service used to obtain tokens and scoped API keys for accessing all ImmPort APIs.
  • Documentation: Auth Service Overview · API Keys

Authentication and API Keys

ImmPort uses scoped API keys for all API access — direct username/password token exchange is no longer supported for general use.

For full instructions on creating and managing API keys, see the API Keys documentation.

To use an API key in requests:

Authorization: Bearer <api_key>

For interactive exploration of the Shared Data API, supply your API key in the Authorize dialog within the Swagger UI.

Tool Type
curl Command-line tool
HTTPie Command-line tool
Postman Desktop REST client (Windows, macOS, Linux)
DHC REST Client Google Chrome extension
Google Chrome Web browser