canonical: https://jentic.com/apis/ncbi.nlm.nih.gov/ncbi-datasets

# Ncbi Nlm Nih Gov NCBI Datasets API

Jentic publishes the only available OpenAPI specification for NCBI Datasets API, keeping it validated and agent-ready. The NCBI Datasets v2 API provides programmatic access to genome assemblies, gene records, taxonomy, BioSample metadata, prokaryote and virus sequence collections, and organelle datasets curated by the National Center for Biotechnology Information. Researchers, bioinformaticians, and AI agents use it to fetch data reports, sequence reports, and downloadable data packages by accession, taxon, BioProject, or BioSample identifier across 107 endpoints.

## For AI agents

Look up genomes, genes, taxonomy, viruses, and BioSample records from NCBI by accession, taxon, or BioProject, and retrieve curated data reports and download summaries.

## Scope

Does not handle clinical patient records, sequence read storage, or PubMed literature search - use for genome, gene, taxonomy, and BioSample reference data only.

## Capabilities

- Retrieve genome assembly reports by accession, taxon, BioProject, or BioSample identifier
- Fetch gene metadata and sequence reports for vertebrate and prokaryote organisms
- Look up taxonomy lineage and link nodes between species and higher ranks
- Search virus and SARS-CoV-2 sequence collections with annotation details
- Generate download summaries and assembly links for bulk data packages
- Query BioSample records and resolve accession-to-assembly relationships

## Use cases

### Genome Assembly Lookup by Accession

Bioinformatics pipelines query the NCBI Datasets API to fetch genome assembly reports by accession (e.g., GCF_000001405.40 for the human reference). The API returns assembly statistics, organism metadata, sequence reports, and download links in a single structured response. Replaces multiple Entrez calls with one v2 endpoint.

Example prompt: Call GET /genome/accession/{accessions}/dataset_report with accession GCF_000001405.40 and parse the assembly statistics

### Taxonomy and Gene Cross-Reference

Agents and analysis scripts resolve taxonomy IDs to genome and gene records to support comparative genomics workflows. The NCBI Datasets API exposes taxonomy nodes, lineage queries, and cross-references to genes and BioSamples without requiring a local NCBI mirror. Useful for researchers building species-level dashboards.

Example prompt: Resolve taxon 9606 via the taxonomy endpoints, then call GET /genome/taxon/{taxons}/dataset_report to retrieve human genome assemblies

### Virus and Pathogen Surveillance

Public health and research teams pull virus sequence records - including SARS-CoV-2 - from NCBI to track variants, sample collection dates, and submitter metadata. The Datasets API provides structured virus queries with annotation context, replacing manual NCBI website searches and enabling pipelines to refresh on a schedule.

Example prompt: Search the virus endpoints for SARS-CoV-2 records updated since 2026-05-01 and download the resulting accessions

### Agent-Driven Genomics Q&A

An AI agent invoked by a researcher answers questions like 'what is the assembly size of the latest mouse reference genome?' by searching Jentic for the right NCBI Datasets operation, loading the schema, and executing the call. Removes the need for the agent to learn NCBI's URL conventions or argument ordering.

Example prompt: Search Jentic for 'fetch mouse genome assembly report' and execute the resolved GET endpoint, returning assembly size to the user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /genome/accession/{accessions}/dataset_report | Get genome assembly report by accession |
| GET | /genome/taxon/{taxons}/dataset_report | Get genome assembly reports by taxon |
| GET | /genome/accession/{accessions}/download_summary | Preview a genome data package download |
| GET | /genome/bioproject/{bioprojects}/dataset_report | Get assemblies by BioProject |
| GET | /genome/biosample/{biosample_ids}/dataset_report | Get assemblies by BioSample |
| GET | /genome/sequence_accession/{accession}/sequence_assemblies | Resolve sequence accession to assemblies |

## Key resources

- **Genome** — Assembly reports, sequence reports, and download summaries by accession, taxon, BioProject, or BioSample
- **Gene** — Gene metadata and cross-references by gene ID or symbol
- **Taxonomy** — Taxonomy lineage and cross-references to genome and gene records
- **Virus** — Virus sequence records including SARS-CoV-2 and other pathogens
- **BioSample** — BioSample metadata and links to assemblies and BioProjects
- **Prokaryote** — Prokaryote-specific assembly and annotation queries
- **Organelle** — Organelle assembly records

## Why Jentic

- **Setup:** Wiring the NCBI Datasets API by hand means learning its optional api-key header on the api.ncbi.nlm.nih.gov host, picking the right report path among many, and handling errors yourself. Through Jentic you install once, import the NCBI Datasets API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** NCBI Datasets puts accessions and taxons in the URL path (/genome/accession/{accessions}/...), so a rule can pin your agent to specific genome resources. Every operation here is a read, so the agent fetches reference data and nothing that changes state.
- **Credential handling:** Your optional NCBI 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 'fetch a genome assembly report by taxon', and Jentic returns the right NCBI Datasets operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NASA APOD API** — Both are U.S. government open-data APIs; NASA APOD covers astronomy imagery while NCBI Datasets covers genomics.
- **EPA Public APIs** — EPA exposes environmental data; combined with NCBI genomic data, it supports environmental-genomics correlation studies.
- **U.S. Census API** — Population and demographic data from Census combines with NCBI biological data for public-health analyses.

## FAQ

### Why is there no official OpenAPI spec for NCBI Datasets API?

NCBI does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call NCBI Datasets 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 NCBI Datasets API use?

NCBI Datasets accepts an optional `api-key` header (or `api_key` query parameter) that raises rate limits from 3 requests/second to 10 requests/second. Jentic stores the key in the encrypted vault when supplied; unauthenticated calls also work for low-volume use.

### Can I download bulk genome data with this API?

The /genome/.../download_summary endpoints return a preview with the size and contents of a data package. Actual download bytes are streamed from the NCBI download service URL returned in the response - the API itself returns metadata and links, not raw FASTA bytes.

### What are the rate limits for the NCBI Datasets API?

NCBI applies 3 requests/second without a key and 10 requests/second with a registered API key. Heavy taxonomy or BioProject batches should use POST endpoints (e.g., POST /genome/dataset_report) which accept arrays of accessions in one call.

### How do I look up a genome assembly through Jentic?

Search Jentic for 'fetch genome assembly report by accession', load the schema for GET /genome/accession/{accessions}/dataset_report, and execute it with the desired accession. The agent receives the structured assembly report directly.

### Is the NCBI Datasets API free?

Yes. NCBI Datasets is funded by the U.S. National Library of Medicine and is free to use. Registering for an API key only changes rate limits, not pricing.

### Can I limit what my agent is allowed to do with the NCBI Datasets API?

Yes. Jentic One runs self-hosted, so you set the rules that decide which NCBI Datasets operations and credentials your agent may use. Because accessions and taxons sit in the URL path, such as /genome/accession/{accessions}/dataset_report, you can pin the agent to specific genome, gene, or taxonomy resources. Every operation here is a read, so the agent can fetch assembly reports, sequence reports, and download summaries but cannot change any data.