Skip to content

Overview

ImmPort provides several focused APIs for accessing, uploading, and integrating immunology research data. Below is a short overview of the primary API families and how they are typically used.

  • Shared Data API (OpenAPI/Swagger)

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

  • GA4GH DRS API

    • Purpose: GA4GH Data Repository Service (DRS) implementation that maps logical DRS object IDs (UUIDs) to the physical methods for retrieving shared files.
    • Notes: DRS is recommended for cloud-native retrieval workflows where a DRS object is resolved to a presigned URL or other transfer mechanism.

  • FHIR (HAPI FHIR Server)

    • Purpose: a FHIR interface exposing a subset of mapped ImmPort data as FHIR ResearchStudy and related resources for interoperability and clinical-research tools.
    • Notes: FHIR endpoints are focused on search and read access to the FHIR-mapped subset; for full dataset access use the Shared Data APIs or download portals.

  • GeneList Resource

    • Purpose: curated gene lists published by ImmPort (e.g., immune-related gene sets). These are distributed as JSON, TXT and GMT files on the public release S3 bucket and are also discoverable from the documentation.
    • Notes: GeneList documentation is part of the Shared Data area and includes direct file URLs (S3) for programmatic download of the lists.

  • 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 authenticated users with appropriate workspace and study permissions. Use scoped API keys (see Authentication section) that include the "upload" scope for write operations.

Authentication and API keys

ImmPort has migrated away from direct username/password token exchange for general API access. Instead, APIs should be accessed using scoped API keys created in the Auth Service UI. Create keys at: https://www.dev.immport.org/auth/api/keys and select the scopes you need (browse, download, upload). The API key JSON returned by the UI contains an "api_key" value — include that value in requests using the Authorization: Bearer header.

For interactive exploration, use the Swagger UI and supply your API key via the Authorize dialog. Programmatic examples in the sections below show the Authorization: Bearer pattern.

Tool Type
Curl Command line tool
HTTPie Command line tool
Postman REST Client App for Google Chrome and OS X
DHC REST Client Google Chrome extension
Google Chrome Google Chrome web browser