canonical: https://jentic.com/apis/illumina.com/illumina-main

# Illumina Connected Analytics API

Jentic publishes the only available OpenAPI specification for Illumina Connected Analytics API, keeping it validated and agent-ready. Illumina Connected Analytics (ICA) is a genomics analysis platform that lets bioinformatics teams run CWL and Nextflow pipelines on managed cloud infrastructure. The API exposes project, pipeline, analysis, and storage credential management so workflows can be triggered, monitored, and tied back to source data. It targets sequencing labs, clinical research groups, and pharma teams that need reproducible, auditable analyses against large genomics datasets.

## For AI agents

Trigger CWL and Nextflow genomics pipelines on Illumina Connected Analytics, list project analyses, and manage storage credentials from an agent.

## Scope

Does not handle sample sequencing, BaseSpace data hosting, or clinical reporting - use for CWL and Nextflow pipeline orchestration on Illumina Connected Analytics only.

## Capabilities

- Launch CWL pipeline runs against a project with input data references and analysis storage selection
- Launch Nextflow pipeline runs and capture run-level outputs for downstream review
- List analyses for a project and retrieve their output artefact manifests
- Register and rotate storage credentials that pipelines use to read and write genomics data
- Deprecate or archive pipelines that should no longer be selectable for new runs
- Enumerate available analysis storage tiers before submitting a pipeline run

## Use cases

### Automated Variant Calling Pipelines

Submit CWL-based variant calling pipelines for whole-genome and whole-exome samples directly from a lab information system. The API accepts project ID, pipeline reference, and input data, runs the analysis on managed compute, and exposes status and outputs through the analyses endpoints. This removes the need for manual launches in the ICA UI for high-throughput sequencing centres.

Example prompt: POST a CWL analysis launch to `/projects/{projectId}/analysis`:cwl with a reference genome input and poll `/projects/{projectId}/analyses` until status is SUCCEEDED.

### Pipeline Output Harvesting

Pull analysis outputs into downstream tertiary analysis or reporting tools by listing analyses for a project and fetching the outputs manifest for each completed run. This supports building data lakes of variant call files and QC metrics without operators copying URLs from the console.

Example prompt: GET `/projects/{projectId}/analyses`, then for each completed analysis call `/projects/{projectId}/analyses/{analysisId}/outputs` and store the output references.

### Storage Credential Lifecycle

Manage cloud storage credentials that pipelines use to read inputs and write outputs. Lab IT can register new credentials when buckets rotate and remove deprecated pipelines so they are never selected for new runs. This reduces the risk of broken runs caused by stale credentials.

Example prompt: POST /storageCredentials with new bucket credentials, then POST `/pipelines/{pipelineId}`:deprecate for any pipelines that depended on the rotated credential.

### Agent-Driven Genomics Workflow Orchestration

An AI agent acts as an orchestration layer for a genomics core, accepting a sample manifest, picking the right pipeline, launching it on ICA, and reporting back when results are ready. Through Jentic the agent searches for the launch operation by intent and calls it without hardcoding endpoint paths, keeping the integration resilient to API changes.

Example prompt: Search Jentic for 'launch a CWL analysis on Illumina Connected Analytics', load the schema, and execute it for a sample whose pipeline reference comes from the lab manifest.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects` | List accessible projects |
| POST | `/projects/{projectId}/analysis:cwl` | Launch a CWL pipeline analysis |
| POST | `/projects/{projectId}/analysis:nextflow` | Launch a Nextflow pipeline analysis |
| GET | `/projects/{projectId}/analyses` | List analyses in a project |
| GET | `/projects/{projectId}/analyses/{analysisId}/outputs` | Retrieve analysis outputs |
| POST | `/storageCredentials` | Register a storage credential |
| POST | `/pipelines/{pipelineId}:deprecate` | Deprecate a pipeline |

## Key resources

- **Projects** — List the projects an account has access to.
- **Analyses** — Launch CWL and Nextflow analyses, list runs, and read outputs.
- **Pipelines** — Deprecate or archive pipelines so they are no longer launchable.
- **Storage Credentials** — Register and list cloud storage credentials used by analyses.
- **Analysis Storage** — Enumerate available analysis storage tiers for run submission.

## Why Jentic

- **Setup:** Wiring Illumina Connected Analytics by hand means setting up its X-API-Key header against the ica.illumina.com host and orchestrating CWL and Nextflow analysis launches yourself. Through Jentic you install once, import the Illumina Connected Analytics API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** ICA puts the project id in the URL path (`/projects/{projectId}/analysis`:cwl, `/projects/{projectId}/analyses`), so a rule can pin your agent to one project. You choose the operations it may call, so actions like deprecating a pipeline or creating storage credentials are not included unless you add them.
- **Credential handling:** Your Illumina ICA API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'launch a CWL analysis on Illumina' or 'get analysis outputs', and Jentic returns the matching ICA operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AWS** — AWS hosts the cloud storage that ICA pipelines read inputs from and write outputs to.
- **Google Cloud Storage** — Google Cloud Storage is an alternative bucket backend for ICA input and output data.

## FAQ

### Why is there no official OpenAPI spec for Illumina Connected Analytics API?

Illumina does not publish a public OpenAPI specification for Connected Analytics. Jentic generates and maintains this spec so that AI agents and developers can call the API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Illumina Connected Analytics API use?

The API uses an API key passed as a header (ApiKeyAuth scheme). Through Jentic the key is held in the encrypted vault and never shipped into agent context, so prompts cannot leak the genomics platform credential.

### Can I launch both CWL and Nextflow pipelines through this API?

Yes. Use POST `/projects/{projectId}/analysis`:cwl for CWL workflows and POST `/projects/{projectId}/analysis`:nextflow for Nextflow pipelines. Both accept input data references and an analysis storage selection.

### How do I retrieve the results of a finished pipeline run?

List analyses for the project with GET `/projects/{projectId}/analyses`, identify the analysis ID for the run, then call GET `/projects/{projectId}/analyses/{analysisId}/outputs` to fetch the output manifest.

### How do I launch a genomics pipeline through Jentic?

Run pip install jentic, then search for 'launch a CWL analysis on Illumina Connected Analytics', load the schema for the matching operation, and execute with the project ID, pipeline reference, and input data references.

### What are the rate limits for the Illumina Connected Analytics API?

The OpenAPI spec does not publish explicit rate limits. Treat pipeline launches as expensive operations and batch list-analyses polling at intervals of 30 seconds or longer to avoid throttling.

### Can I limit what my agent is allowed to do with the Illumina Connected Analytics API?

Yes. Jentic One is self-hosted, so your own rules decide which operations and credentials the agent may use. Because the project ID sits in the URL path (for example `/projects/{projectId}/analysis`:cwl and `/projects/{projectId}/analyses`), you can pin the agent to a single project and allow only launch and read operations. Actions like deprecating a pipeline or registering storage credentials stay off limits unless you explicitly add them to what the agent may call.